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The NetRExx Programming Series 


This book is part of a library, the NetRExx Programming Series, documenting the 
NetRExx programming language and its use and applications. This section lists the 
other publications in this series, and their roles. These books can be ordered in conve- 
nient hardcopy and electronic formats from the Rexx Language Association. 


Quick Start Guide This guide is meant for an audience that has done some pro- 
gramming and wants to start quickly. It starts with a quick 
tour of the language, and a section on installing the NetRExx 
translator and how to run it. It also contains help for trou- 
bleshooting if anything in the installation does not work as 
designed, and states current limits and restrictions of the 
open source reference implementation. 





Programming Guide The Programming Guide is the one manual that at the same 
time teaches programming, shows lots of examples as they 
occur in the real world, and explains about the internals of 
the translator and how to interface with it. 





Language Reference _Referred to as the NRL, this is the formal definition for the 
language, documenting its syntax and semantics, and pre- 
scribing minimal functionality for language implementors. 
It is the definitive answer to any question on the language, 
and as such, is subject to approval of the NetRexx Architec- 
ture Review Board on any release of the language (including 
its NRL). 


Pipelines Reference The Data Flow oriented companion to NetRExx, with its 
CMS Pipes compatible syntax, is documented in this manual. 
It discusses installing and running Pipes for NetRExx, and 
has ample examples of defining your own stages in NetRExx. 
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Typographical conventions 


In general, the following conventions have been observed in the NetRexx publications: 


¢ Body text is in this font 

« Examples of language statements are in a bold type 

¢ Variables or strings as mentioned in source code, or things that appear on the con- 
sole, are in a typewriter type 

¢ Items that are introduced, or emphasized, are in an italic type 

* Included program fragments are listed in this fashion: 


Listing 1: Example Listing 


1 -- Salute the reader 
2 say 'hello reader' 


« Syntax diagrams take the form of so-called Railroad Diagrams to convey structure, 
mandatory and optional items 


Properties 


rae 
visibility modifier deprecated 
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Introduction 


NetRExx is a general-purpose programming language inspired by two very different 
programming languages, RExx and Java . It is designed for people, not computers. In 
this respect it follows Rexx closely, with many of the concepts and most of the syn- 
tax taken directly from RExx or its object-oriented version, Object RExx. From Java it 
derives static typing, binary arithmetic, the object model, and exception handling. The 
resulting language not only provides the scripting capabilities and decimal arithmetic 
of Rexx, but also seamlessly extends to large application development with fast binary 
arithmetic. 

The open source reference implementation (version 3 and later) of NetRExx produces 
classes for the Java Virtual Machine, and in so doing demonstrates the value of that con- 
crete interface between language and machine: NetRExx classes and Java classes are 
entirely equivalent - NetRExx can use any Java class (and vice versa) and inherits the 
portability and robustness of the Java environment. 


This document is in three parts: 


1. The objectives of the NetRexx language and the concepts underlying its design, 
and acknowledgements. 


2. An overview and introduction to the NetRExx language. 
3. The definition of the language. 


Appendices include a sample NetRExx program, a description of an experimental fea- 
ture, and some details of the contents of the netrexx. lang package. 


1.1 Language Objectives 


This document describes a programming language, called NetRExx, which is derived 
from both RExx and Java. NetRExx is intended as a dialect of RExx that can be as ef- 
ficient and portable as languages such as Java, while preserving the low threshold to 
learning and the ease of use of the original Rexx language. 


1.1.1 Features of RExx 


The Rexx programming language was designed with just one objective: to make pro- 
gramming easier than it was before. The design achieved this by emphasizing readability 
and usability, with a minimum of special notations and restrictions. It was consciously 





1 Cowlishaw, M. E, The REXX Language (second edition), ISBN 0-13-780651-5, Prentice-Hall, 1990. 
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designed to make life easier for its users, rather than for its implementers. One impor- 
tant feature of RExx syntax is keyword safety. Programming languages invariably need 
to evolve over time as the needs and expectations of their users change, so this is an 
essential requirement for languages that are intended to be executed from source. 


Keywords in Rexx are not globally reserved but are recognized only in context. This 
language attribute has allowed the language to be extended substantially over the years 
without invalidating existing programs. Even so, some areas of RExx have proved dif- 
ficult to extend - for example, keywords are reserved within instructions such as do. 
Therefore, the design for NetRExx takes the concept of keyword safety even further than 
in Rexx, and also improves extensibility in other areas. 


‘The great strengths of Rexx are its human-oriented features, including 


¢ simplicity 

* coherent and uncluttered syntax 

* comprehensive stringhandling 

* case-insensitivity 

¢ arbitrary precision decimal arithmetic. 


Care has been taken to preserve these. Conversely, its interpretive nature has always 
entailed a lack of efficiency: excellent RExx compilers do exist, from IBM and other 
companies, but cannot offer the full speed of statically-scoped languages such as C2 or 
Javal, 


1.1.2 Influence of Java 


The system-independent design of RExx makes it an obvious and natural fit to a system- 
independent execution environment such as that provided by the Java Virtual Machine 
(JVM). The JVM, especially when enhanced with “just-in-time” bytecode compilers that 
compile bytecodes into native code just before execution, offers an effective and attractive 
target environment for a language like Rexx. 


Choosing the JVM as a target environment does, however, place significant constraints 
on the design of a language suitable for that environment. For example, the semantics of 
method invocation are in several ways determined by the environment rather than by 
the source language, and, to a large extent, the object model (class structure, etc.) of the 
Java environment is imposed on languages that use it. 


Also, Java maintains the C concept of primitive datatypes; types (such as int, a 32-bit 
signed integer) which allow efficient use of the underlying hardware yet do not describe 
true objects. These types are pervasive in classes and interfaces written in the Java lan- 
guage; any language intending to use Java classes effectively must provide access to these 
types. 

Equally, the exception (error handling) model of Java is pervasive, to the extent that meth- 
ods must check certain exceptions and declare those that are not handled within the 
method. This makes it difficult to fit an alternative exception model. 





Kernighan, B. W,, and Ritchie, D. M., The C Programming Language (second edition), ISBN 0-13-110362-8, Prentice- Hall, 
1988. 
Gosling, J. A., et al. The Java Language Specification, ISBN 0-201-63451-1, Addison-Wesley, 1996. 
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The constraints of safety, efficiency, and environment necessitated that NetRExx would 
have to differ in some details of syntax and semantics from Rexx; unlike Object Rexx, 
it could not be a fully upwards-compatible extension of the languagel. The need for 
changes, however, offered the opportunity to make some significant simplifications and 
enhancements to the language, both to improve its keyword safety and to strengthen 
other features of the original Rexx design§. Some additions from Object Rexx and ANSI 
Rexx are also included. 


Similarly, the concepts and philosophy of the Rexx design can profitably be applied to 
avoid many of the minor irregularities that characterize the C and Java language fam- 
ily, by providing suitable simplifications in the programming model. For example, the 
NetRexx looping construct has only one form, rather than three, and exception handling 
can be applied to all blocks rather than requiring an extra construct. Also, as in RExx, 
all NetRExx storage allocation and de-allocation is implicit - an explicit new operator 
is not required. 


Further, the human-oriented design features of RExx (case-insensitivity for identifiers, 
type deduction from context, automatic conversions where safe, tracing, and a strong 
emphasis on string representations of common values and numbers) make program- 
ming for the Java environment especially easy in NetRExx. 


1.1.3 A hybrid or a whole? 


As in other mixtures, not all blends are a success; when first designing NetRExx, it was 
not at all obvious whether the new language would be an improvement on its parents, 
or would simply reflect the worst features of both. 


The fulcrum of the design is perhaps the way in which datatyping is automated with- 
out losing the static typing supported by Java. Typing in NetRExx is most apparent at 
interfaces - where it provides most value - but within methods it is subservient and 
does not obscure algorithms. A simple concept, binary classes, also lets the programmer 
choose between robust decimal arithmetic and less safe (but faster) binary arithmetic 
for advanced programming where performance is a primary consideration. 


The “seamless” integration of types into what was previously an essentially typeless lan- 
guage does seem to have been a success, offering the advantages of strong typing while 
preserving the ease of use and speed of development that RExx programmers have en- 
joyed. 

The end result of adding Java typing capabilities to the Rexx language is a single language 
that has both the Rexx strengths for scripting and for writing macros for applications 
and the Java strengths of robustness, good efficiency, portability, and security for appli- 
cation development. 





4Nash, S.C., Object-Oriented REXX in Goldberg, G, and Smith, P. H. III, The RExx Handbook, pp115-125, ISBN 0-07-023682- 
8, McGraw-Hill, Inc., New York, 1992. 

5See Cowlishaw, M. EF, The Early History of REXX, IEEE Annals of the History of Computing, ISSN 1058-6180, Vol 16, No. 
4, Winter 1994, pp15-24, and Cowlishaw, M. F, The Future of RExx, Proceedings of Winter 1993 Meeting/SHARE 80, Volume II, 
p-2709, SHARE Inc., Chicago, 1993. 

®See American National Standard for Information Technology - Programming Language REXX, X3.274-1996, American 
National Standards Institute, New York, 1996. 


1.2 Language Concepts 


As described in the last section, NetRExx was created by applying the philosophy of the 
Rexx language to the semantics required for programming the Java Virtual Machine 
(JVM). Despite the assumption that the JVM is a “target environment” for NetREXx, it is 
intended that the language not be environment-dependent; the essentials of the language 
do not depend on the JVM. Environment- dependent details, such as the primitive types 
supported, are not part of the language specification. 


The primary concepts of Rexx have been described before, in The Rexx Language, but 
it is worth repeating them and also indicating where modifications and additions have 
been necessary to support the concepts of statically-typed and object-oriented environ- 
ments. The remainder of this section is therefore a summary of the principal concepts 
of NetRExx. 


1.2.1 Readability 


One concept was central to the evolution of Rexx syntax, and hence NetRExx syntax: 
readability (used here in the sense of perceived legibility). Readability in this sense is a 
somewhat subjective quality, but the general principle followed is that the tokens which 
form a program can be written much as one might write them in Western European 
languages (English, French, and so forth). Although NetRExx is more formal than a 
natural language, its syntax is lexically similar to everyday text. 


The structure of the syntax means that the language is readily adapted to a variety of 
programming styles and layouts. This helps satisfy user preferences and allows a lexical 
familiarity that also increases readability. Good readability leads to enhanced under- 
standability, thus yielding fewer errors both while writing a program and while reading 
it for information, debugging, or maintenance. 


Important factors here are: 


1. Punctuation and other special notations are required only when absolutely nec- 
essary to remove ambiguity (though punctuation may often be added according 
to personal preference, so long as it is syntactically correct). Where notations are 
used, they follow established conventions. 


2. The language is essentially case-insensitive. A NetREXx programmer may choose 
a style of use of uppercase and lowercase letters that he or she finds most helpful 
(rather than a style chosen by some other programmer). 


3. The classical constructs of structured and object-oriented programming are avail- 
able in NetRExx, and can undoubtedly lead to programs that are easier to read than 
they might otherwise be. The simplicity and small number of constructs also make 
NetRexx an excellent language for teaching the concepts of good structure. 


4. Loose binding between the physical lines in a program and the syntax of the lan- 
guage ensures that even though programs are affected by line ends, they are not 
irrevocably so. A clause may be spread over several lines or put on just one line; 
this flexibility helps a programmer lay out the program in the style felt to be most 
readable. 


1.2.2 Natural data typing and decimal arithmetic 


“Strong typing’, in which the values that a variable may take are tightly constrained, has 
been an attribute of some languages for many years. The greatest advantage of strong typ- 
ing is for the interfaces between program modules, where errors are easy to introduce 
and difficult to catch. Errors within modules that would be detected by strong typing 
(and which would not be detected from context) are much rarer, certainly when com- 
pared with design errors, and in the majority of cases do not justify the added program 
complexity. 

NetRexx, therefore, treats types as unobtrusively as possible, with a simple syntax for 
type description which makes it easy to make types explicit at interfaces (for example, 
when describing the arguments to methods). 


By default, common values (identifiers, numbers, and so on) are described in the form 
of the symbolic notation (strings of characters) that a user would normally write to rep- 
resent those values. This natural datatype for values also supports decimal arithmetic 
for numbers, so, from the user’s perspective, numbers look like and are manipulated as 
strings, just as they would be in everyday use on paper. 


When dealing with values in this way, no internal or machine representation of charac- 
ters or numbers is exposed in the language, and so the need for many data types is re- 
duced. There are, for example, no fundamentally different concepts of integer and real; 
there is just the single concept of number. The results of all operations have a defined 
symbolic representation, and will therefore act consistently and predictably for every 
correct implementation. 


This concept also underlies the BASIC! language; indeed, Kemeny and Kurtz’s vision for 
BASIC included many of the fundamental principles that inspired Rexx. For example, 
Thomas E. Kurtz wrote: 


“Regarding variable types, we felt that a distinction between ‘fixed’ and ‘floating’ was less justified in 1964 
than earlier ... to our potential audience the distinction between an integer number and a non-integer 
number would seem esoteric. A number is a number is a number” 


For RExx, intended as a scripting language, this approach was ideal; symbolic operations 
were all that were necessary. 


For NetRExx, however, it is recognized that for some applications it is necessary to take 
full advantage of the performance of the underlying environment, and so the language 
allows for the use and specification of binary arithmetic and types, if available. A very 
simple mechanism (declaring a class or method to be binary) is provided to indicate to 
the language processor that binary arithmetic and types are to be used where applicable. 
In this case, as in other languages, extra care has to be taken by the programmer to avoid 
exceeding limits of number size and so on. 





7Kemeny, J. G. and Kurtz, T. E., BASIC programming, John Wiley & Sons Inc., New York, 1967. 
8Kurtz, T. E., BASIC in Wexelblat, R. L. (Ed), History of Programming Languages, ISBN 0-12-745040-8, Academic Press, New 
York 1981. 


1.2.3 Emphasis on symbolic manipulation 


Many values that NetRExx manipulates are (from the user’s point of view, at least) in 
the form of strings of characters. Productivity is greatly enhanced if these strings can be 
handled as easily as manipulating words on a page or in a text editor. NetRExx therefore 
has a rich set of character manipulation operators and methods, which operate on values 
of type Rexx (the name of the class of NetRExx strings). 


Concatenation, the most common string operation, is treated specially in NetRexx. In 
addition to a conventional concatenate operator (“||”), the novel blank operator from 
REXX concatenates two data strings together with a blank in between. Furthermore, if 
two syntactically distinct terms (such as a string and a variable name) are abutted, then 
the data strings are concatenated directly. These operators make it especially easy to build 
up complex character strings, and may at any time be combined with the other operators. 








For example, the say instruction consists of the keyword say followed by any expression. 
In this instance of the instruction, if the variable n has the value “6” then 


say ’Sorry,’ n*100/50’% were rejected’ 
would display the string 
Sorry, 12% were rejected 


Concatenation has a lower priority than the arithmetic operators. The order of evalu- 
ation of the expression is therefore first the multiplication, then the division, then the 
concatenate-with-blank, and finally the direct concatenation. Since the concatenation 
operators are distinct from the arithmetic operators, very natural coercion (automatic 
conversion) between numbers and character strings is possible. Further, explicit type- 
casting (conversion of types) is effected by the same operators, at the same priority, mak- 
ing for a very natural and consistent syntax for changing the types of results. For example, 


i=int 100/7 


would calculate the result of 100 divided by 7, convert that result to an integer (assuming 
int describes an integer type) and then assign it to the variable i. 


1.2.4 Nothing to declare 


Consistent with the philosophy of simplicity, NetRExx does not require that variables 
within methods be declared before use. Only the properties! of classes - which may form 
part of their interface to other classes — need be listed formally. 


Within methods, the type of variables is deduced statically from context, which saves 
the programmer the menial task of stating the type explicitly. Of course, if preferred, 
variables may be listed and assigned a type at the start of each method. 





°Class variables and instance variables. 


1.2.5 Environment independence 


The core NetRExx language is independent of both operating systems and hardware. 
NetRExx programs, though, must be able to interact with their environment, which 
implies some dependence on that environment (for example, binary representations of 
numbers may be required). Certain areas of the language are therefore described as being 
defined by the environment. 


Where environment-independence is defined, however, there may be a loss of efficiency 
- though this can usually be justified in view of the simplicity and portability gained. 


As an example, character string comparison in NetRExx is normally independent of case 
and of leading and trailing blanks. (The string “ Yes ” means the same as “yes” in most 
applications.) However, the influence of underlying hardware has often subtly affected 
this kind of design decision, so that many languages only allow trailing blanks but not 
leading blanks, and insist on exact case matching. By contrast, NetRExx provides the 
human-oriented relaxed comparison for strings as default, with optional “strict com- 
parison” operators. 


1.2.6 Limited span syntactic units 


The fundamental unit of syntax in the NetRExx language is the clause, which is a piece 
of program text terminated by a semicolon (usually implied by the end of a line). The 
span of syntactic units is therefore small, usually one line or less. This means that the 
syntax parser in the language processor can rapidly detect and locate errors, which in 
turn means that error messages can be both precise and concise. 


It is difficult to provide good diagnostics for languages (such as Pascal and its derivatives) 
that have large fundamental syntactic units. For these languages, a small error can often 
have a major or distributed effect on the parser, which can lead to multiple error messages 
or even misleading error messages. 


1.2.7 Dealing with reality 


A computer language is a tool for use by real people to do real work. Any tool must, 
above all, be reliable. In the case of a language this means that it should do what the user 
expects. User expectations are generally based on prior experience, including the use of 
various programming and natural languages, and on the human ability to abstract and 
generalize. 


It is difficult to define exactly how to meet user expectations, but it helps to ask the 
question “Could there be a high astonishment factor associated with this feature?”. If a 
feature, accidentally misused, gives apparently unpredictable results, then it has a high 
astonishment factor and is therefore undesirable. 


Another important attribute of a reliable software tool is consistency. A consistent lan- 
guage is by definition predictable and is often elegant. The danger here is to assume that 
because a rule is consistent and easily described, it is therefore simple to understand. Un- 
fortunately, some of the most elegant rules can lead to effects that are completely alien 
to the intuition and expectations of a user who, after all, is human. 
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These constraints make programming language design more of an art than a science, if 
the usability of the language is a primary goal. The problems are further compounded 
for NetRExx because the language is suitable for both scripting (where rapid develop- 
ment and ease of use are paramount) and for application development (where some pro- 
grammers prefer extensive checking and redundant coding). These conflicting goals are 
balanced in NetRExx by providing automatic handling of many tasks (such as conver- 
sions between different representations of strings and numbers) yet allowing for “strict” 
options which, for example, may require that all types be explicit, identifiers be identical 
in case as well as spelling, and so on. 


1.2.8 Be adaptable 


Wherever possible NetRExx allows for the extension of instructions and other language 
constructs, building on the experience gained with Rexx. For example, there is a useful 
set of common characters available for future use, since only small set is used for the few 
special notations in the language. 


Similarly, the rules for keyword recognition allow instructions to be added whenever re- 
quired without compromising the integrity of existing programs. There are no reserved 
keywords in NetRExx; variable names chosen by a programmer always take precedence 
over recognition of keywords. This ensures that NetRExx programs may safely be exe- 
cuted, from source, at a time or place remote from their original writing — even if in the 
meantime new keywords have been added to the language. 


A language needs to be adaptable because it certainly will be used for applications not fore- 
seen by the designer. Like all programming languages, NetRExx may (indeed, probably 
will) prove inadequate for certain future applications; room for expansion and change is 
included to make the language more adaptable and robust. 


1.2.9 Keep the language small 


NetReExx is designed as a small language. It is not the sum ofall the features of RExx and 
of Java; rather, unnecessary features have been omitted. The intention has been to keep 
the language as small as possible, so that users can rapidly grasp most of the language. 
This means that: 

« the language appears less formidable to the new user 

¢ documentation is smaller and simpler 


¢ the experienced user can be aware of all the abilities of the language, and so has the 
whole tool at his or her disposal 


* there are few exceptions, special cases, or rarely used embellishments 

* the language is easier to implement. 
Many languages have accreted “neat” features which make certain algorithms easier to 
express; analysis shows that many of these are rarely used. As a rough rule-of-thumb, 


features that simply provided alternative ways of writing code were added to Rexx and 
NetRexx only if they were likely to be used more often than once in five thousand clauses. 
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1.2.10 No defined size or shape limits 


The language does not define limits on the size or shape of any of its tokens or data (al- 
though there may be implementation restrictions). It does, however, define a few min- 
imum requirements that must be satisfied by an implementation. Wherever an imple- 
mentation restriction has to be applied, it is recommended that it should be of such a 
magnitude that few (if any) users will be affected. 


Where arbitrary implementation limits are necessary, the language requires that the im- 
plementer use familiar and memorable decimal values for the limits. For example 250 
would be used in preference to 255, 500 to 512, and so on. 


1.3. Acknowledgements 


Much of NetRExx is based on earlier work, and Iam indebted to the hundreds of people 
who contributed to the development of RExx, Object RExx, and Java. 


In the 1990s I gained many insights from the deliberations of the members of the X3J18 
technical committee, which, under the remarkable chairmanship of Brian Marks, led to 
the 1996 ANSI Standard for Rexx. Many of the committee's suggestions are incorporated 
in NetRExx. 


Equally important have been the comments and feedback from the pioneering users of 
NetReExx, and all those people who sent me comments on the language either directly or 
in the NetRExx mailing list or forum. I would especially like to thank Ian Brackenbury, 
Barry Feigenbaum, Davis Foulger, Norio Furukawa, Dion Gillard, Martin Lafaix, Max 
Marsiglietti, and Trevor Turton for their insightful comments and encouragement. 


Talso thank IBM; my appointment as an IBM Fellow made it possible to make the imple- 
mentation of NetRExx a reality in months rather than years. IBM has also donated the 
NetRexx implementation to the Rexx Language Association, with special thanks due 
to Matthew Emmons for piloting NetRexx through the convoluted legal and other pro- 
cesses, and to René Jansen for massaging the NetRExx reference implementation into 
shape for its Open Source release. 


Finally, this document has relied on old but trusted technology for its creation: its GML 
markup was processed using macros originally written by Bob O’Hara, and formatted 
using SCRIPT/VS, the IBM Document Composition Facility. Geoff Bartlett provided 
critical advice on character sets and fonts for the NetRExx book. This version uses a set 
of RExx programs to translate that same GML markup to OpenOffice Document Text 
format (XML files). 


Mike Cowlishaw, 1997 and 2009 
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Introduction to the current edition 


After the open sourcing of the NetRExx reference implementation in 2011 the RExxLA 
NetRexx ARB (Architecture Review Board), in which Mike Cowlishaw takes part as 
Language Architect, took responsibility for the definition of the language. Starting from 3.00 
version 3.00, changes in the language definition™ in this publication will be marked with 

the introducing release number, in the form of a margin note. 

For this version of the NetRExx Language Reference, a NetRExx program was used to 
translate the original GML markup to XqIpx. This edition describes the 3.07-BETA 
version of the language and supercedes all earlier versions. The previously included 3.07 
chapter “A Quick Tour of the NetRexx Language” can now be exclusively found in the 
NetRexx Quickstart Guide. 


René Vincent Jansen, July 28, 2018 





10 This publication is traditionally known as NRL, short for NetRexx Language Reference. This title however, has (for reasons of 
clarity for new users) been changed in the filename of the PDF version of the book in favour of a longer and more descriptive name. 
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NetRExx Language Definition 


This part of the document describes the NetRExx language, version 3.07-BETA. This 
version includes the original NetRExx language reference together with additions 
made from 1997 through 2000 and previously published in the NetRExx Language Sup- 
plement. 


The language is described first in terms of the characters from which it is composed 
and its low-level syntax, and then progressively through more complex constructions. 
Finally, special sections describe the semantics of the more complicated areas. 


Some features of the language, such as options keywords and binary arithmetic, are 
implementation-dependent. Rather than leaving these important aspects entirely ab- 
stract, this description includes summaries of the treatment of such items in the ref- 
erence implementation of NetRexx. The reference implementation is based on the Java 
environment and class libraries. 


Paragraphs that refer to the reference implementation, and are therefore not strictly part of 
the language definition, are shown in italics, like this one. 





1) The NetRExx Language, M. F. Cowlishaw, ISBN 0-13-806332-X, Prentice-Hall, 1997 
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Notations 


In this part of the book, various notations such as changes of font are used for clarity. 
Within the text, a sans-serif bold font is used to indicate keywords, and an italic font is 
used to indicate technical terms. An italic font is also used to indicate a reference to a 
technical term defined elsewhere or a word in a syntax diagram that names a segment of 
syntax. 


Similarly, in the syntax diagrams in this book, words (symbols) in the sans-serif bold font 
also denote keywords or sub-keywords, and words (such as expression) in italics denote 
a token or collection of tokens defined elsewhere. The brackets [ and ] delimit optional 
(and possibly alternative) parts of the instructions, whereas the braces { and } indicate 
that one of a number of alternatives must be selected. An ellipsis (...) following a bracket 
indicates that the bracketed part of the clause may optionally be repeated. 


Occasionally in syntax diagrams (e.g., for indexed references) brackets are ’real” (that is, 
a bracket is required in the syntax; it is not marking an optional part). These brackets are 
enclosed in single quotes, thus: ’[’ or ’]’. 


Note that the keywords and sub-keywords in the syntax diagrams are not case-sensitive: 
the symbols "IF” "If” and iF” would all match the keyword shown in a syntax diagram 
as if. 


Note also that most of the clause delimiters (”;”) shown can usually be omitted as they 
will be implied by the end ofa line. 
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Characters and Encodings 


In the definition of a programming language it is important to emphasize the distinc- 
tion between a character and the coded representation 4 (encoding) of a character. The 
character ”A’, for example, is the first letter of the English (Roman) alphabet, and this 
meaning is independent of any specific coded representation of that character. Different 
coded character sets (such as, for example, the ASCII and EBCDIC™ codes) use quite 
different encodings for this character (decimal values 65 and 193, respectively). Except 
where stated otherwise, this book uses characters to convey meaning and not to imply 
a specific character code (the exceptions are certain operations that specifically convert 
between characters and their representations). At no time is NetRExx concerned with 
the glyph (actual appearance) of a character. 


5.1 Character Sets 


Programming in the NetRexx language can be considered to involve the use of two 
character sets. The first is used for expressing the NetRExx program itself, and is the 
relatively small set of characters described in the next section. The second character set 
is the set of characters that can be used as character data by a particular implementation 
of a NetRExx language processor. This character set may be limited in size (sometimes 
to a limit of 256 different characters, which have a convenient 8-bit representation), or 
it may be much larger. The Unicode [4 character set, for example, allows for 1,114,112 
code points, of which currently 128,000 are defined as characters. These are represented, 
depending on the serialization format, in one to four bytes. 


Usually, most or all of the characters in the second (data) character set are also allowed 
within a NetRExx program, but only within commentary or immediate (literal) data. 
The NetRexx language explicitly defines the first character set, in order that programs 
will be portable and understandable; at the same time it avoids restrictions due to the 
language itself on the character set used for data. However, where the language itself 
manipulates or inspects the data (as when carrying out arithmetic operations), there may 
be requirements on the data character set (for example, numbers can only be expressed 
if there are digit characters in the set). 





12 These terms have the meanings as defined by the International Organization for Standardization, in ISO 2382 :cit.Data pro- 
cessing - Vocabulary:ecit.. 

13 American Standard Code for Information Interchange. 

14 Extended Binary Coded Decimal Interchange Code. 

15 The Unicode Standard, version 6.0., The Unicode Consortium, Mountain View, 2011, ISBN 09781936213016. 
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Structure and General Syntax 


A NetRexx program is built up out of a series of clauses that are composed of: zero or 
more blanks (which are ignored); a sequence of tokens (described in this section); zero 
or more blanks (again ignored); and the delimiter ”;” (semicolon) which may be implied 
by line-ends or certain keywords. Conceptually, each clause is scanned from left to right 


before execution and the tokens composing it are resolved. 


Identifiers (known as symbols) and numbers are recognized at this stage, comments (de- 
scribed below) are removed, and multiple blanks (except within literal strings) are re- 
duced to single blanks. Blanks adjacent to operator characters (see page 22) and special 
characters (see page 23) are also removed. 


6.1 Blanks and White Space 


Blanks (spaces) may be freely used in a program to improve appearance and layout, and 
most are ignored. Blanks, however, are usually significant 


* within literal strings (see below) 


¢ between two tokens that are not special characters (for example, between two sym- 
bols or keywords) 


* between the two characters forming a comment delimiter 
¢ immediately outside parentheses (”(” and ”)”) or brackets (”[” and ”]”). 


For implementations that support tabulation (tab) and form feed characters, these char- 
acters outside of literal strings are treated as if they were a single blank; similarly, if the 
last character in a NetRExx program is the End-of-file character (EOF, encoded in ASCII 
as decimal 26), that character is ignored. 


6.2 Comments 


Commentary is included in a NetRExx program by means of comments. Two forms of 
comment notation are provided: line comments are ended by the end of the line on which 
they start, and block comments are typically used for more extensive commentary. 


Line comments A line comment is started by a sequence of two adjacent hyphens 
(“- -”); all characters following that sequence up to the end of the line are then 
ignored by the NetRExx language processor. 

Example: 


i=j+7 -- this line comment follows an assignment 


Block comments A block comment is started by the sequence of characters ”/*”, and is 
ended by the same sequence reversed, ”*/”. Within these delimiters any characters 
are allowed (including quotes, which need not be paired). Block comments may 
be nested, which is to say that ”/*” and ”*/” must pair correctly. Block comments 
may be anywhere, and may be of any length. When a block comment is found, it 
is treated as though it were a blank (which may then be removed, if adjacent to a 
special character). 

Example: 


/*x This is a valid block comment x/ 


The two characters forming a comment delimiter (”/*” or ”*/”) must be adjacent 
(that is, they may not be separated by blanks or a line-end). 


Note: It is recommended that NetRExx programs start with a block comment that de- 
scribes the program. Not only is this good programming practice, but some implemen- 
tations may use this to distinguish NetRExx programs from other languages. Imple- 
mentation minimum: Implementations should support nested block comments to a 
depth of at least 10. The length of a comment should not be restricted, in that it should 
be possible to “comment out” an entire program. 


6.3 Tokens 


The essential components of clauses are called tokens. These may be of any length, unless 
limited by implementation restrictions, § and are separated by blanks, comments, ends 
of lines, or by the nature of the tokens themselves. 


The tokens are: 


Literal strings A sequence including any characters that can safely be represented in 
an implementation ™ and delimited by the single quote character (’) or the double- 
quote (”). Use”” to include a” in a literal string delimited by ”, and similarly use two 
single quotes to include a single quote in a literal string delimited by single quotes. 
A literal string is a constant and its contents will never be modified by NetRExx. 
Literal strings must be complete on a single line (this means that unmatched quotes 
may be detected on the line that they occur). Any string with no characters (i.e., a 
string of length 0) is called a null string. 

Examples: 


>Fred’ 
> AY’ 
"Don’t Panic!” 


” : x”? 





16 Wherever arbitrary implementation restrictions are applied, the size of the restriction should be a number that is readily mem- 
orable in the decimal system; that is, one of 1, 25, or 5 multiplied by a power of ten. 500 is preferred to 512, the number 250 is more 
natural” than 256, and so on. Limits expressed in digits should be a multiple of three. 

17 Some implementations may not allow certain "control characters” in literal strings. These characters may be included in literal 
strings by using one of the escape sequences provided. 
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TABLE 1: Escape sequences 























\t the escape sequence represents a tabulation (tab) character 

\n the escape sequence represents a new-line (line feed) character 

\r the escape sequence represents a return (carriage return) character 

\f the escape sequence represents a form-feed character 

\ the escape sequence represents a double-quote character 

Y the escape sequence represents a single-quote character 

\ the escape sequence represents a backslash character 

\- the escape sequence represents a “null” character (the character whose encoding equals 


zero), used to indicate continuation in a say instruction 





\O(zero) the escape sequence represents a “null” character (the character whose encoding equals 


zero); an alternative to \- 





\xhh 


the escape sequence represents a character whose encoding is given by the two hexadecimal 
digits ("hh”) following the ”x”. If the character encoding for the implementation requires 
more than two hexadecimal digits, they are padded with zero digits on the left. 


\uhhhh the escape sequence represents a character whose encoding is given by the four hexadecimal 


digits (?hhhh”) following the ”u”. It is an error to use this escape if the character encoding 
for the implementation requires fewer than four hexadecimal digits. 


>You shouldn’’t’ /*x Same as ”You shouldn’t” x*/ 
ae /* A null string */ 


Within literal strings, characters that cannot safely or easily be represented (for ex- 
ample *control characters”) may be introduced using an escape sequence. An escape 
sequence starts with a backslash (”\”), which must then be followed immediately by 
one of the following (letters may be in either uppercase or lowercase) - see table 
Hexadecimal digits for use in the escape sequences above may be any decimal digit 
(0-9) or any of the first six alphabetic characters (a-f), in either lowercase or up- 
percase. Examples: 


>You shouldn\’t’ /*x Same as ”You shouldn’t” x/ 
>\x6d\u0066\x63’ =(/x In Unicode: ’mfc’ x/ 
>\\\u005C’ /* In Unicode, two backslashes */ 


Implementation minimum: Implementations should support literal strings of at 
least 100 characters. (But note that the length of string expression results, etc., 
should have a much larger minimum, normally only limited by the amount of stor- 
age available.) 


Symbols Symbols are groups of characters selected from the Roman alphabet in upper- 


case or lowercase (A-Z, a-z), the Arabic numerals (0-9), or the characters under- 
score, dollar, and euro!4 (”_$ €”) Implementations may also allow other alphabetic 
and numeric characters in symbols to improve the readability of programs in lan- 
guages other than English. These additional characters are known as extra letters 
and extra digits. 

Examples: 





18 Note that only UTF8-encoded source files can currently use the euro character. 
19 Tt is expected that implementations of NetRExx will be based on Unicode or a similarly rich character set. However, portability 
to implementations with smaller character sets may be compromised when extra letters or extra digits are used in a program. 
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Oo 
Oo 


DanYrOgof 

minx 

Elan 

$Virtual3D 

A symbol may include other characters only when the first character of the symbol 
is a digit (0-9 or an extra digit). In this case, it is a numeric symbol - it may include 
a period (”.”) and it must have the syntax of a number. This may be simple number, 
which is a sequence of digits with at most one period (which may not be the final 
character of the sequence), or it may be a hexadecimal or binary numeric symbol(see 
page 24) , or it may be a number expressed in exponential notation. 

A number in exponential notation is a simple number followed immediately by 
the sequence ”E” (or ”e”), followed immediately by a sign (”+” or ”-”), © followed 
immediately by one or more digits (which may not be followed by any other symbol 
characters). 


Examples: 


1 

1.3 
12.007 
17.3E-12 
3e+12 
0.Q3E+9 


When extra digits are used in numeric symbols, they must represent values in the 
range zero through nine. When numeric symbols are used as numbers, any extra 
digits are first converted to the corresponding character in the range 0-9, and then 
the symbol follows the usual rules for numbers in NetREexx (that is, the most sig- 
nificant digit is on the left, etc.). 
In the reference implementation, the extra letters are those characters (excluding A-Z, 
a-z, and underscore) that result in 1 when tested with 
java.lang.Character.isJavaldentifierPart. Similarly, the extra digits are those char- 
acters (excluding 0-9) that result in 1 when tested with java.lang.Character.isDigit. 
The meaning of a symbol depends on the context in which it is used. For example, 
a symbol may be a constant (if a number), a keyword, the name of a variable, or 
identify some algorithm. 
It is recommended that the dollar and euro only be used in symbols in mechan- 
ically generated programs or where otherwise essential. Implementation mini- 
mum: Implementations should support symbols of at least 50 characters. (But note 
that the length of its value, if it is a string variable, should have a much larger limit.) 
Operator characters The characters + - * % |/ & \= < > are used (sometimes in 
combination) to indicate operations (see page 7) in expressions. A few of these 
are also used in parsing templates, and the equals sign is also used to indicate as- 
signment. Blanks adjacent to operator characters are removed, so, for example, the 
sequences: 


345>=123 


345 >=123 
345 >= 123 





20 The sign in this context is part of the symbol; it is not an operator. 
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345 > = 123 


are identical in meaning. Some of these characters may not be available in all char- 
acter sets, and if this is the case appropriate translations may be used. Note: The 
sequences ”-”, ”/*”, and ”*/” are comment delimiters, as described earlier. The se- 
quences ”++” and ”\\” are not valid in NetRExx programs. 

Special characters The characters .,;) (] [ together with the operator characters have 
special significance when found outside of literal strings, and constitute the set of 
special characters. They all act as token delimiters, and blanks adjacent to any of 
these (except the period) are removed, except that a blank adjacent to the outside 
of a parenthesis or bracket is only deleted if it is also adjacent to another special 
character (unless this is a parenthesis or bracket and the blank is outside it, too). 
Some of these characters may not be available in all character sets, and if this is the 
case appropriate translations may be used. 


To illustrate how a clause is composed out of tokens, consider this example: 
>REPEAT’ B+ 35 


This is composed of six tokens: a literal string, a blank operator (described later), a sym- 
bol (which is probably the name ofa variable), an operator, a second symbol (a number), 
and a semicolon. The blanks between the ”B” and the ”+” and between the ”+” and the 
”3” are removed. However one of the blanks between the REPEAT” and the ”B” remains 
as an operator. Thus the clause is treated as though written: 


REPEAT’ B+3; 


6.4 Implied semicolons and continuations 


A semicolon (clause end) is implied at the end of each line, except if: 


1. The line ends in the middle of a block comment, in which case the clause continues 
at the end of the block comment. 

2. The last token was a hyphen. In this case the hyphen is functionally replaced by a 
blank, and hence acts as a continuation character. 


This means that semicolons need only be included to separate multiple clauses on a single 
line. 


Notes: 


1. A comment is not a token, so therefore a comment may follow the continuation 
character on a line. 

2. Semicolons are added automatically by NetRExx after certain instruction keywords 
when in the correct context. The keywords that may have this effect are else, 
finally, otherwise, then; they become complete clauses in their own right when 
this occurs. These special cases reduce program entry errors significantly. 
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6.5 The case of names and symbols 


In general, NetRExx is a case-insensitive language. ‘That is, the names of keywords, vari- 
ables, and so on, will be recognized independently of the case used for each letter in a 
name; the name ’Swildon” would match the name *swilDon”. 


NetRexx, however, uses names that may be visible outside the NetRExx program, and 
these may well be referenced by case-sensitive languages. Therefore, any name that has 
an external use (such as the name of a property, method, constructor, or class) has a 
defined spelling, in which each letter of the name has the case used for that letter when 
the name was first defined or used. 


Similarly, the lookup of external names is both case-preserving and case-insensitive. If 
a class, method, or property is referenced by the name ’Foo’, for example, an exact-case 
match will first be tried at each point that a search is made. If this succeeds, the search 
for a matching name is complete. If it does not succeed, a case-insensitive search in the 
same context is carried out, and if one item is found, then the search is complete. If more 
than one item matches then the reference is ambiguous, and an error is reported. 


Implementations are encouraged to offer an option that requires that all name matches 
are exact (case-sensitive), for programmers or house-styles that prefer that approach to 
name matching. 


6.6 Hexadecimal and binary numeric symbols 


A hexadecimal numeric symbol describes a whole number, and is of the form nXstring. 
Here, n is a simple number with no decimal part (and optional leading insignificant 
zeros) which describes the effective length of the hexadecimal string, the X (which may 
be in lowercase) indicates that the notation is hexadecimal, and string is a string of one 
or more hexadecimal characters (characters from the ranges ”a-f”, “A-F’, and the digits 
0-9”), 

The string is taken as a signed number expressed in n hexadecimal characters. If neces- 
sary, string is padded on the left with ”0” characters (note, not "sign-extended”) to length 
n characters. 


If the most significant (left-most) bit of the resulting string is zero then the number is 
positive; otherwise it is a negative number in twos-complement form. In both cases it 
is converted to a NetRExx number which may, therefore, be negative. The result of the 
conversion is a number comprised of the Arabic digits 0-9, with no insignificant leading 


”» 9 


zeros but possibly with a leading ”-”. 


The value n may not be less than the number of characters in string, with the single 
exception that it may be zero, which indicates that the number is always positive (as 
though n were greater than the the length of string). 


Examples: 


1x8 == -8 
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0x08 —_ 


0x10 == 16 
Ox81 == 129 
2x81 == -127 
3x81 == 129 
4x81 == 129 
04x81 == 129 
16x81 == 129 
4xFO81 == -3967 
8xFO81 == 61569 
OXfO081 == 61569 


A binary numeric symbol describes a whole number using the same rules, except that 
the identifying character is B or b, and the digits of string must be either 0 or 1, each 
representing a single bit. 


Examples: 


1b0 == 
1b1 eS Sl 
0b10 == 
Ob100 == 4 
4b1000 == -8 
8B1000 == 


Note: Hexadecimal and binary numeric symbols are a purely syntactic device for repre- 
senting decimal whole numbers. That is, they are recognized only within the source of 
a NetRExx program, and are not equivalent to a literal string with the same characters 
within quotes. 
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Types and Classes 


Programs written in the NetRExx language manipulate values, such as names, numbers, 
and other representations of data. All such values have an associated type (also known 
as a signature). 


The type of a value is a descriptor which identifies the nature of the value and the oper- 
ations that may be carried out on that value. 


A type is normally defined by a class, which is a named collection of values (called prop- 
erties) and procedures (called methods) for carrying out operations on the properties. 


For example, a character string in NetRExx is usually of type RExx, which will be im- 
plemented by the class called RExx. The class RExx defines the properties of the string 
(a sequence of characters) and the methods that work on strings. This type of string may 
be the subject of arithmetic operations as well as more conventional string operations 
such as concatenation, and so the methods implement string arithmetic as well as other 
string operations. 


The names of types can further be qualified by the name of a package where the class is 
held. See the package instruction for details of packages; in summary, a package name 
is a sequence of one or more non-numeric symbols, separated by periods. Thus, if the 
Rexx class was part of the netrexx.lang package, © then its qualified type would be 
netrexx.lang.REXX. 


In general, only the class name need be specified to refer to a type. However, if a class 
of the same name exists in more than one known (imported) package, then the name 
should be qualified by the package name. That is, if the use of just the class name does 
not uniquely identify the class then the reference is ambiguous and an error is reported. 


7.1 Primitive types 


Implementations may optionally provide primitive types for efficiency. Primitive types 
are “built-in” types that are not necessarily implemented as classes. They typically repre- 
sent concepts native to the underlying environment (such as 32-bit binary integer num- 
bers) and may exhibit semantics that are different from other types. NetRExx, however, 
makes no syntax distinction in the names of primitive types, and assumes binary con- 
structors (see page exist for primitive values. 

Primitive types are necessary when performance is an overriding consideration, and so 


this definition will assume that primitive types corresponding to the common binary 
number formats are available and will describe how they differ from other types, where 





21 This is in fact where it may be found in the reference implementation. 
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appropriate. 


In the reference implementation, the names of the primitive types are: 
boolean char byte short int long float double 


where the first two describe a single-bit value and Unicode character respectively, and the 
remainder describe signed numbers of various formats. The main difference between these 
and other types is that the primitive types are not a subclass of Object, so they cannot be 
assigned to a variable of type Object or passed to methods “by reference”. To use them 
in this way, an object must be created to “wrap” them; Java provides classes for this (for 
example, the class Long). 


7.2 Dimensioned types 


Another feature that is provided for efficiency is the concept of dimensioned types, which 
are types (normal or primitive) that have an associated dimension (in the sense of the 
dimensions of an array). Dimensioned values are described in detail in the section on 
Arrays (see page 62) . 

The dimension of a dimensioned type is represented in NetRExx programs by square 
brackets enclosing zero or more commas, where the dimension is given by the number 
of commas, plus one. A dimensioned type is distinct from the type of the same name but 
with no dimensions. 


Examples: 


Rexx 
int 
Rexx[ ] 
intL,,] 


The examples show a normal type, a primitive type, and a dimensioned version of each 
(of dimension 1 and 3 respectively). The latter type would result from constructing an 
array thus: 


myarray=int[10,10,10] 


That is, the dimension of the type matches the count of indexes defined for the array. 


7.3 Minor and Dependent classes 


A minor class in NetREXx is a class whose name is qualified by the name of another class, 
called its parent. This qualification is indicated by the form of the name of the class: the 
short name of the minor class is prefixed by the name of its parent class (separated by a 
period). For example, if the parent is called Foo then the full name of a minor class Bar 
would be written Foo. Bar. 


A dependent class is a minor class that has a link to its parent class that allows a child 
object simplified access to its parent object and its properties. 
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These refinements of classes and are described in the section Minor and Dependent 


classes (see page {135} . 
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Terms 


A term in NetRExx is a syntactic unit which describes some value (such as a literal string, 
a variable, or the result of some computation) that can be manipulated in a NetRExx 
program. 


Terms may be either simple (consisting of a single element) or compound (consisting of 
more than one element, with a period and no other characters between each element). 


8.1 Simple terms 


A simple term may be: 


- A literal string (see page 20) - a character string delimited by quotes, which is a 
constant. 


A symbol (see page . A symbol that does not begin with a digit identifies a 
variable, a value, or a type. One that does begin with a digit is a numeric symbol, 
which is a constant. 


A method call (see page B7) , which is of the form 


symbol ([expression[ ,expresstion]...]) 


An indexed reference (see page 61l) , which is of the form 


symbol’ [’ Lexpresston[,expression]...]’]’ 


« An array initializer (see page 63)) , which is of the form 


> L’expresston[,expression]...’]’ 
p »EXP 


+ A sub-expression (see page 52) , which consists of any expression enclosed within a 
left and a right parenthesis. 


Blanks are not permitted between the symbol in a method call and the ”(’; or between 
the symbol in an indexed reference and the ”[”. 


Within simple terms, method calls with no arguments (that is, with no expressions be- 
tween the parentheses) may be expressed without the parentheses provided that they 
refer to a method in the current class (or to a static method in a class used by the current 
class) and do not refer to a constructor (see page 41)) . An implementation may optionally 
provide a mechanism that disallows this parenthesis omission. 





22 The notations ’ [’ and ’]” indicate square brackets appearing in the NetRExx program. 
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8.2 Compound terms 


Compound terms may start with any simple term, and, in addition, may start with a 
qualified class name (see page or a qualified constructor (see page B7) . These last 
two both start with a package name (a sequence of non-numeric symbols separated by 
periods and ending in a period). 


This first part of a compound term is known as the stub of the term. Example stubs: 


"A string” 

Arca 

12.10 

paint(g) 

indexedVar[i+1] 

(7A” *string”) 

java. lang.Math -- qualified class name 
netrexx.lang.Rexx(1) -- qualified constructor 


All stubs are syntactically valid terms (either simple or compound) and may optionally 
be followed by a continuation, which is one or more additional non-numeric symbols, 
method calls, or indexed references, separated from each other and from the stub by 
connectors which are periods. Example compound terms: 


"A rabbit”.word(2).pos(’b’) 
Fluffy.left(3) 

12.10.max(j) 
paint(g).picture 
indexedVar[it1].length 

("A” *string”) .word(1) 
java. lang.Math.PI 

java. lang.Math. lLog(10) 


Within compound terms, method calls with no arguments (that is, with no expressions 
between the parentheses) may be expressed without the parentheses provided that they 
do not refer to a constructor (see page 41) . For example, the term: 


Thread. currentThread().suspend() 
could be written: 
Thread. currentThread. suspend 


An implementation may optionally provide a mechanism that disallows this parenthesis 
omission. 


8.3 Evaluation of terms 


Simple terms are evaluated as a whole, as described below. Compound terms are evalu- 
ated from left to right. First the stub is evaluated according to the rules detailed below. 
The type of the value of the stub then qualifies the next element of the term (if any) which 
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is then evaluated (again, the exact rules are detailed below). This process is then repeated 
for each element in the term. 


For instance, for the example above: 
"A rabbit”.word(2).pos(’b’) 
the evaluation proceeds as follows: 


1. The stub (“A rabbit”) is evaluated, resulting in a string of type RExx. 

2. Because that string is of type RExx, the RExx class is then searched for the word 
method. This is then invoked on the string, with argument 2. In other words, the 
word method is invoked with the string ”A rabbit” as its current context (the prop- 
erties of the Rexx class when the method is invoked reflect that value). 

This returns a new string of type RExx, ”rabbit” (the second word in the original 
string). 

3. In the same way as before, the pos method of the RExx class is then invoked on 
the new string, with argument ”b”. 

This returns a new string of type RExx, ”3” (the position of the first "b” in the 
previous result). 


This value, ”3”, is the final value of the term. 


The remainder of this section gives the details of term evaluation; it is best skipped on 
first reading. 


8.4 Simple term evaluation 


All simple terms may also be used as stubs, and are evaluated in precisely the same way 
as stubs, as described below. For example, numeric symbols are evaluated as though they 
were enclosed in quotes; their value is a string of type REXx. 


In binary classes (see page |71)) , however, simple terms that are strings or numeric sym- 


bols are given an implementation-defined string or primitive type respectively, as de- 
scribed in the section on Binary values and operations (see page |165)) 


8.5 Stub evaluation 


A terms stub is evaluated according to the following rules: 


- If the stub is a literal string, its value is the string, of type RExx, constructed from 
that literal. 

« If the stub is a numeric symbol, its value is the string, of type REXxx, constructed 
from that literal (as though the literal were enclosed in quotes). 

¢ If the stub is an unqualified method or constructor call, or a qualified constructor 
call, then its value and type is the result of invoking the method identified by the 
stub, as described in Methods and Constructors (see page B7) . 

¢ If the stub is a (non-numeric) symbol, then its value and type will be determined 
by whichever of the following is first found: 
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1. A local variable or method argument within the current method, or a property 
in the current class. 

2. A method whose name matches the symbol, and takes no arguments, and that 
is not a constructor, in the current class. 23 If the stub is part of a compound 
symbol, then it may also be ina superclass, searching upwards from the current 
class. 

3. A static or constant property, or a static method, 24 whose name matches the 
symbol (and that takes no arguments, if a method) in a class listed in the 
uses phrase of the class instruction. Each class from the list is searched for a 
matching property or method, and then its superclasses are searched upwards 
from the class in the same way; this process is repeated for each of the classes, 
in the order specified in the list. 

4, One of the allowed special words described in Special words and methods (see 
page , such as this or version. 

5. The short name of a known class or primitive type (in which case the stub has 
no value, just a type). 

- If the stub is an indexed reference, then its value and type will be determined by 
whichever of the following is first found: 

1. The symbol naming the reference is an undimensioned local variable or 
method argument within the current method, or a property in the current 
class, which has type RExx. In this case, the reference is to an indexed string 
(see page 61) ; the expressions within the brackets must be convertible to type 
RExx, and the type of the result will be RExx. 

2. The symbol naming the reference is a dimensioned local variable or method 
argument within the current method, or a property in the current class. In this 
case, the reference is to an array (see page 62) , and the expressions within the 
brackets must be convertible to whole numbers allowed for array indexes. The 
type of the result will have the type of the array, with dimensions reduced by 
the number of dimensions specified in the stub. For example, if the array foo 
was of type Baa[,,,] and the stub referred to foo[1,2], then the result would be 
of type Baa|[,]. It would have been an error for the stub to have specified more 
than four dimensions. 

3. The symbol naming the reference is the name of a static or constant property 
in a class listed in the uses phrase of the class instruction. Each class from 
the list is searched in the same way as for symbols, above. The reference may 
be to an indexed string or an array, as for properties in the current class. 

4. The symbol naming the reference is the name of a primitive type or the short 
name of a known class, and there are no expressions within the brackets (just 
optional commas). In this case, the stub describes a dimensioned type (see page 


5. The symbol naming the reference is the name of a primitive type or is the 
short name of a known class, and there are one or more expressions within 
the brackets. In this case, the reference is to an array constructor (see page 64) ; 
the expressions within the brackets must be convertible to non-negative whole 
numbers allowed for array indexes, and the value is an array of the specified 





23 Unless parenthesis omission is disallowed by an implementation option, such as options strictargs. 
24 Unless parenthesis omission is disallowed by an implementation option, such as options strictargs. 


34 


type, dimensions, and size. 


If the stub is a sub-expression, then its value and type will be determined by eval- 
uating the expression (see page 47) within the parentheses. 


If the stub starts with the name of a package, then it will either describe a qualified 
type (see page 27) or a qualified constructor (see page . Its type will be same 
in either case, and if a constructor then its value will be the value returned by the 
constructor. 


If the stub is not followed by further segments, the final value and type of the term is the 
value and type of the stub. 


8.6 


Continuation evaluation 


Each segment of a term’s continuation is evaluated from left to right, according to the 
type of the evaluation of the term so far (the continuation type) and the syntax of the new 
segment: 


If the segment is a method call, then its value and type is the result of invoking 
the matching method in the class defining the continuation type (or a superclass 
or subclass of that class), as described in Methods and Constructors (see page BA) F 
Note that method calls in term continuations cannot be constructors. 


If the stub is an indexed reference, then it will refer to a property in the class defining 
the continuation type (or a superclass of that class). That property will either be an 
undimensioned NetRExx string (type REXXx) or a dimensioned array. In either case, 
it is evaluated in the same way as an indexed reference found in the stub, except that 
it is not necessarily in the current class, cannot be an array constructor, and cannot 
result in a dimensioned type. 


If the segment is a symbol, then it refers to either a property or a method in the 
class defining the continuation type (or a superclass of that class). B53 

The search for the property or method starts with the class defining the contin- 
uation type. If a property name matches, it is used; if not, a method of the same 
name and having no arguments (or only optional arguments) will match. If nei- 
ther property nor method is found, then the same search is applied to each of the 
continuation class's superclasses in turn, starting with the class that it extends. 

As a convenient special case, if the property or method is not found, then if the 
segment is the final segment of the term and is the simple symbol length and the 
continuation type is a single-dimensioned array, then the segment evaluates to the 
size of the array. This will be a non-negative whole number of an appropriate prim- 
itive type (or of type RExx if there is no appropriate type). 


The final value and type of the term is the value and type determined by the evaluation 
of the last segment of the continuation. 





5 Unless parenthesis omission is disallowed by an implementation option, such as options strictargs, in which case it can 
only be a property. 
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8.7 Arrays in terms 
If a partially-evaluated term results in a dimensioned array (see page , its type is 
treated as type Object so that evaluation of the term can continue. For example, in 


ca=char[] ”tosh” 
say ca.toString() 


the variable ca is an array of characters; in the expression on the second line the method 
toString() of the class Object will be found. 24 





26 In the reference implementation, this would return an identifier for the object. 
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Methods and Constructors 


Instructions in NetRExx are grouped into methods, which are named routines that al- 
ways belong to (are part of) a class. 


Methods are invoked by being referenced in a term (see page Bl) , which may be part of 
an expression or be a clause in its own right (a method call instruction). In either case, 
the syntax used for a method invocation is: 


symbol ([expression[,expression]...]) 


The symbol, which must be non-numeric, is called the name of the method. It is impor- 
tant to note that the name of the method must be followed immediately by the ” (’; with 
no blank in between, or the construct will not be recognized as a method call (a blank op- 
erator would be assumed at that point instead). The expressions (separated by commas) 
between the parentheses are called the arguments to the method. Each argument expres- 
sion may include further method calls. The argument expressions are evaluated in turn 
from left to right and the resulting values are then passed to the method (the procedure 
for locating the method is described below). The method then executes some algorithm 
(usually dependent on any arguments passed, though arguments are not mandatory) 
and will eventually return a value. This value is then included in the original expression 
just as though the entire method reference had been replaced by the name of a variable 
whose value is that returned data. 


For example, the substr method is provided for strings of type RExx and could be used 
as: 


c=’ abcdefghijk’ 
a=c.substr(3,7) 
/x would set A to ”cdefghi” */ 


Here, the value of the variable c is a string (of type RExx). The substr (substring) method 
of the RExx class is then invoked, with arguments 3 and 7, on the value referred to by c. 
That is, the the properties available to (the context of) the substr method are the proper- 
ties constructed from the literal string ’abcdefghijk. The method returns the substring 
of the value, starting at the third character and of length seven characters. 


A method may have a variable number of arguments: only those required need be spec- 
ified. For example, ABCDEF’substr(4) would return the string *DEF’, as the substr 
method will assume that the remainder of the string is to be returned if no length is 
provided. 
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Method invocations that take no arguments may omit the (empty) parentheses in cir- 
cumstances where this would not be ambiguous. See the section on Terms (see page 
for details. 


Implementation minimum: At least 10 argument expressions should be allowed in a 
method call. 


9.1 Method call instructions 


When a clause in a method consists of just a term, and the final part of the term is a 
method invocation, the clause is a method call instruction: 


symbol ([expression[,expresstion]...])3 


The method is being called as a subroutine of the current method, and any returned value 
is discarded. In this case (and in this case only), the method invoked need not return a 
value (that is, the return instruction that ends it need not specify an expression). 74 


A method call instruction that is the first instruction in a constructor (see below) can 
only invoke the special constructors this and super. 


9.2 Method resolution (search order) 


Method resolution in NetRExx proceeds as follows: 


¢ If the method invocation is the first part (stub) of a term, then: 

1. The current class is searched for the method (see below for details of search- 
ing). 

2. If not found in the current class, then the superclasses of the current class are 
searched, starting with the class that the current class extends. 

3. If still not found, then the classes listed in the uses phrase of the class instruc- 
tion are searched for the method, which in this case must be a static method 
(see page 95) . Each class from the list is searched for the method, and then its 
superclasses are searched upwards from the class; this process is repeated for 
each of the classes, in the order specified in the list. 

4. If still not found, the method invocation must be a constructor (see below) 
and so the method name, which may be qualified by a package name, should 
match the name of a primitive type or a known class (type). The specified class 
is then searched for a constructor that matches the method invocation. 

« If the method invocation is not the first part of the term, then the evaluation of the 
parts of the term to the left of the method invocation will have resulted in a value 
(or just a type), which will have a known type (the continuation type). Then: 

1. The class that defines the continuation type is searched for the method (see 
below for details of searching). 





27 A method call instruction is equivalent to the cal1 instruction of other languages, except that no keyword is required. 
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2. If not found in that class, then the superclasses of that class are searched, start- 
ing with the class that that class extends. 
If the search did not find a method, an error is reported. 
If the search did find a method, that is the method which is invoked, except in one 
case: 
¢ Ifthe evaluation so far has resulted in a value (an object), then that value may 
have a type which is a subclass of the continuation type. If, within that subclass, 
there is a method that exactly overrides (see page AQ) the method that was 
found in the search, then the method in the subclass is invoked. 
This case occurs when an object is earlier assigned to a variable of a type which is 
a superclass of the type of the object. This type simplification hides the real type 
of the object from the language processor, though it can be determined when the 
program is executed. 


Searching for a method in a class proceeds as follows: 


1. Candidate methods in the class are selected. To be a candidate method: 


* the method must have the same name as the method invocation (independent 
of the case (see page 24) of the letters of the name) 

* the method must have the same number of arguments as the method invoca- 
tion (or more arguments, provided that the remainder are shown as optional 
in the method definition) 

* it must be possible to assign the result of each argument expression to the type 
of the corresponding argument in the method definition (if strict type check- 
ing is in effect, the types must match exactly). 

2. If there are no candidate methods then the search is complete; the method was not 
found. 


3. If there is just one candidate method, that method is used; the search is complete. 


4. If there is more than one candidate method, the sum of the costs of the conver- 
sions (see page 45)) from the type of each argument expression to the type of the 
corresponding argument defined for the method is computed for each candidate 
method. 

5. The costs of those candidates (if any) whose names match the method invocation 
exactly, including in case, are compared; if one has a lower cost than all others, that 
method is used and the search is complete. 

6. The costs of all the candidates are compared; if one has a lower cost than all others, 
that method is used and the search is complete. 

7. If there remain two or more candidates with the same minimum cost, the method 
invocation is ambiguous, and an error is reported. 


Note: When a method that is not an exact match to a call is found in a class, superclasses 
of that class are also searched for methods which may have a lower-cost of conversion 
and the method with the lowest cost, hence the closest match, is used to resolve the 
search. 


The current method of method resolution has been chosen to maximize interoperability 
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with Java-language programs. 


9.3. Method overriding 


A method is said to exactly override a method in another class if 


1. the method in the other class has the same name as the current method 

2. the method in the other class is not private 

3. the other class is a superclass of the current class, or is a class that the current class 
implements (or is a superclass of one of those classes). 

4. the number and type of the arguments of the method in the other class exactly 
match the number and type of the arguments of the current method (where subsets 
are also checked, if either method has optional arguments). 


For example, the RExx class includes a substr (see page |191)) method, which takes from 
one to three strings of type RExx. In the class: 


class mystring extends Rexx 
method substr(n=Rexx, Length=Rexx) 
return this.reverse.substr(n, length) 


method substr(n=int, lLength=int) 
return this.reverse.substr (Rexx n, Rexx length) 


the first method exactly overrides the substr method in the RExx class, but the second 
does not, because the types of the arguments do not match. 


A method that exactly overrides a method is assumed to be an extension of the overrid- 
den method, to be used in the same way. For such a method, the following rules apply: 


+ It must return a value of the same type as the overridden method (or none, if the 
overridden method returns none). 

¢ It must be at least as visible as the overridden routine. For example, if the overridden 

routine is public then it must also be public. 

If the overridden method is static then it must also be static. 

If the overridden method is not static then it must not be static. 

« If the underlying implementation checks exceptions (see page , only those 
checked exceptions that are signalled by the overridden method may be left un- 
caught in the current method. 


9.4 Return Types 


NetRexx allows covariant return types such as have been allowed in Java since the ver- 
sion 1.5 release. Prior to Java 1.5, in order for a method to override or implement a 





28 This in contrast to all versions before 3.02, where this rule was: When a method is found in a class, superclasses of that class are 
not searched for methods, even though a lower-cost method may exist in a superclass.. The latter was chosen to guard the program 
optimally against changes in superclasses. 

?° observing what is stated in the next paragraph 
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method from another class, the return type of the methods had to be an exact match. 
Since the Java 1.5 release, methods which override a superclass method or implement an 
interface class method are allowed to have a return type which is a subclass of the return 
type of the method replaced or implemented. An exact match is no longer required. 


9.5 Constructor methods 


As described above, methods are usually invoked in the context of an existing value or 
type. A special kind of method, called a constructor method, is used to actually create a 
value of a given type (an object). 


Constructor methods always have the same short name as the class in which they are 
found, and construct and return a value of the type defined by that class (sometimes 
known as an instance of that class). If the class is part of a package, then the constructor 
call may be qualified by the package name. 


Example constructors: 


File(’Dan.yr.Ogof’ ) 
java.io.File(’Speleogroup. letter’) 
Rexx(’some words’) 
netrexx. Lang. Rexx(1) 


There will always be at least one constructor if values can be created for a class. NetREXx 
will add a default public constructor that takes no arguments if no constructors are pro- 
vided, unless the components of the class are all static or constant, or the class is an 
interface class. 


All constructors follow the same rules as other methods, and in addition: 


1. Constructor calls always include parentheses in the syntax, even if no arguments 
are supplied. This distinguishes them from a reference to the type of the same name. 


2. Constructors must call a constructor of their superclass (the class they extend) be- 
fore they carry out any initialization of their own. This is so any initialization car- 
ried out by the superclass takes place, and at the appropriate moment. Only after 
this call is complete can they make any reference to the special words this or super 
(see page 
Therefore, the first instruction in a constructor must be either a call to the super- 
class, using the special constructor super() (with optional arguments), or a call to 
to another constructor in the same class, using the special constructor this() (with 
optional arguments). In the latter case, eventually a constructor that explicitly calls 
super() will be invoked and the chain of local constructor calls ends. 

As a convenience, NetRExx will add a default call to super(), with no arguments, 
if the first instruction in a constructor is not a call to this() or super(). 


3. The properties of a constructed value are initialized, in the order given in the pro- 
gram, after the call to super() (whether implicit or explicit). 

4. By definition, constructors create a value (object) whose type is defined by the cur- 
rent class, and then return that value for use. Therefore, the returns keyword on 
the method instruction (see page 93) that introduces the constructor is optional (if 
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given, the type specified must be that of the class). Similarly, the only possible forms 
of the return instruction used in a constructor are either ”return this;, which re- 
turns the value that has just been constructed, or just ”return;”, in which case, the 
“this” is assumed (this form will be assumed at the end of a method, as usual, if 
necessary). 


Here is an example of a class with two constructors, showing the use of this() and su- 
per(), and taking advantage of some of the assumptions: 


Listing 9.1: MyChars.nrx 


class MyChars extends SomeClass 


properties private 
/y% the data 'in' the object ,/ 
value=char[] 


/% construct the object from a char array ,/ 
method MyChars(array=char[]) 

/% initialize superclass ,;/ 

super () 

value=array -- save the value 


/x construct the object from a String ,/ 
method MyChars(s=String) 
/% convert to char[] and use the above ,;/ 
this(s.toCharArray()) 


Objects of type MyChars could then be created thus: 
myvar=MyChars(”From a string”) 


or by using an argument that has type char[]. 
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Type conversions 


As described in the section on Types and classes (see page 27), all values that are ma- 
nipulated in NetRExx have an associated type. On occasion, a value involved in some 
operation may have a different type than is needed, and in this case conversion of a value 
from one type to another is necessary. 


NetRexx considerably simplifies the task of programming, without losing robustness, by 
making many such conversions automatic. It will automatically convert values providing 
that there is no loss of information caused by the automatic conversion (or if there is, an 
exception would be raised). 


Conversions can also be made explicit by concatenating a type to a value (see page 50) 
and in this case less robust conversions (sometimes known as casts) may be effected. See 
below for details of the permitted automatic and explicit conversions. 


Almost all conversions carry some risk of failure, or have a performance cost, and so it is 
expected that implementations will provide options to either report costly conversions 
or require that programmers make all conversions explicit. 4 Such options might be 
recommended for certain critical programming tasks, but are not necessary for general 
programming. 


10.1 Permitted automatic conversions 


In general, the semantics of a type is unknown, and so conversion (from a source type to 
a target type) is only possible in the following cases: 


« The target type and the source type are identical (the trivial case). 

« The target type is a superclass of the source type, or is an interface class imple- 
mented by the source type. This is called type simplification, and in this case the 
value is not altered, no information is lost, and an explicit conversion may be used 
later to revert the value to its original type. 

¢ The source type has a dimension, and the target type is Object. 

« The source type is null and the target type is not primitive. 

¢ The target and source types have known semantics (that is, they are ’well-known” 
to the implementation) and the conversion can be effected without loss of infor- 
mation (other than knowledge of the original type). These are called well-known 
conversions. 


Necessarily, the well-known conversions are implementation-dependent, in that they 
depend on the standard classes for the implementation and on the primitive types sup- 





30 In the reference implementation, options strictassign may be used to disallow automatic conversions. 
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ported (if any). Equally, it is this automatic conversion between strings and the primitive 
types of an implementation that offer the greatest simplifications of NetREXx program- 
ming. 


For example, if the implementation supported an int binary type (perhaps a 32-bit in- 
teger) then this can safely be converted to a NetRExx string (of type RExx). Hence a 
value of type int can be added to a number which is a NetRExx string (resulting in a 
NetReExx string) without concern over the difference in the types of the two terms used 
in the operation. 


Conversely, converting a long integer to a shorter one without checking for truncation 
of significant digits could cause a loss of information and would not be permitted. 


In the reference implementation, the semantics of each of the following types is known to 
the language processor (the first four are all string types, and the remainder are known as 
binary numbers): 

* netrexx.lang.REXx - the NetRExx string class 

« java.lang.String - the Java string class 

¢ char - the Java primitive which represents a single character 

¢ char[] - an array of chars 

* boolean - a single-bit primitive 

byte, short, int, long, - signed integer primitives (8, 16, 32, or 64 bits) 

¢ float, double - floating-point primitives (32 or 64 bits) 


Under the rules described above, the following well-known conversions are permitted: 


« REXxx to binary number, char[], String, or char 


String to binary number, char[], REXx, or char 


¢ char to binary number, char[], String, or REXx 


char[] to binary number, REXx, String, or char 
¢ binary number to REXx, String, char[], or char 


¢ binary number to binary number (if no loss of information can take place - no sign, 
high order digits, decimal part, or exponent information would be lost) 


Notes: 


1. Some of the conversions can cause a run-time error (exception), as when a string 
represents a number that is too large for an int and a conversion to int is attempted, 
or when a string that does not contain exactly one character is converted to a char. 


2. The boolean primitive is treated as a binary number that may only take the values 
0 or 1. A boolean may therefore be converted to any binary number type, as well as 
any of the string (or char) types, as the character 0” or ”1”. Similarly, any binary 
number or string can be converted to boolean (and must have a value of 0 or 1 for the 
conversion to succeed). 


3. The char type is a single-character string (it is not a number that represents the en- 
coding of the character). 
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10.2 Permitted explicit conversions 


Explicit conversions are permitted for all permitted automatic conversions and, in ad- 
dition, when: 


The target type is a subclass of the source type, or implements the source type. This 
conversion will fail if the value being converted was not originally of the target type 
(or a subclass of the target type). 

¢ Both the source and target types are primitive and (depending on the implemen- 
tation) the conversion may fail or truncate information. 

¢ The target type is RExx or a well-known string type (all values have an explicit 
string representation). 


10.3 Costs of conversions 


All conversions are considered to have a cost, and, for permitted automatic conversions, 
these costs are used to select a method for execution when several possibilities arise, 
using the algorithm described in Methods and Constructors (see page B8) . 


For permitted automatic conversions, the cost of a conversion from a source type to a 
target type will range from zero through some arbitrary positive value, constrained by 
the following rules: 


« The cost is zero only if the source and target types are the same, or if the source 
type is null and the target type is not primitive. 

¢ Conversions from a given primitive source type to different primitive target types 
should have different costs. For example, conversion of an 8-bit number to a 64-bit 
number might cost more than conversion of a 8-bit number to a 32-bit number. 

* Conversions that may require the creation of a new object cost more than those 
that can never require the creation of a new object. 

* Conversions that may fail (raise an exception) cost more than those that may re- 
quire the creation of an object but can never fail. 


Within these constraints, exact costs are arbitrary, and (because they mostly involve 
implementation-dependent primitive types) are necessarily implementation-dependent. 
The intent is that the ’best performance” method be selected when there is a possibility 
of more than one. 
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Expressions and Operators 


Many clauses can include expressions. Expressions in NetRExx are a general mechanism 
for combining one or more data items in various ways to produce a result, usually dif- 
ferent from the original data. Expressions consist of one or more terms (see page BI) , 
such as literal strings, symbols, method calls, or sub-expressions, and zero or more oper- 
ators that denote operations to be carried out on terms. Most operators act on two terms, 
and there will be at least one of these dyadic operators between every pair of terms. 
There are also prefix (monadic) operators, that act on the term that is immediately to the 
right of the operator. There may be one or more prefix operators to the left of any term, 
provided that adjacent prefix operators are different. 


Evaluation of an expression is left to right, modified by parentheses and by operator 
precedence (see page 62) in the usual ”algebraic” manner. Expressions are wholly eval- 
uated, except when an error occurs during evaluation. 


As each term is used in an expression, it is evaluated as appropriate and its value (and 
the type of that value) are determined. 


The result of any operation is also a value, which may be a character string, a data object 
of some other type, or (in special circumstances) a binary representation of a charac- 
ter or number. The type of the result is well-defined, and depends on the types of any 
terms involved in an operation and the operation carried out. Consequently, the result 
of evaluating any expression is a value which has a known type. 


Note that the NetRexx language imposes no restriction on the maximum size of results, 
but there will usually be some practical limitation dependent upon the amount of storage 
and other resources available during execution. 


11.1 Operators 


The operators in NetRExx are constructed from one or more operator characters (see 
page 22). Blanks (and comments) adjacent to operator characters have no effect on the 
operator, and so the operators constructed from more than one character may have em- 
bedded blanks and comments. In addition, blank characters, where they occur between 
tokens within expressions but are not adjacent to another operator, also act as an opera- 
tor. The operators may be subdivided into five groups: concatenation, arithmetic, com- 
parative, logical, and type operators. The first four groups work with terms whose type is 
well-known’ (that is, strings, or known types that can be be converted to strings without 
information loss). The operations in these groups are defined in terms of their operations 
on strings. 





31 One operator, direct concatenation, is implied if two terms abut (see page f&) . 
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TABLE 2: Concatenation operators 


(blank) Concatenate terms with one blank in between. 





|| Concatenate without an intervening blank. 





(abuttal) Concatenate without an intervening blank. 


TABLE 3: Arithmetic operators 























+ Add 

- Subtract 

= Multiply 

/ Divide 

% Integer divide. Divide and return the integer part of the result. 

// Remainder. Divide and return the remainder (this is not modulo, as the result may be neg- 
ative). 

ae Power. Raise a number to a whole number power. 

Prefix- Same as the subtraction: ”0-number”. 





Prefix+ Same as the addition: ”0+number”. 


11.1.1 Concatenation 


The concatenation operators are used to combine two strings to form one string by ap- 
pending the second string to the right-hand end of the first string. The concatenation 
may occur with or without an intervening blank: Concatenation without a blank may 
be forced by using the || operator, but it is useful to remember that when two terms 
are adjacent and are not separated by an operator, 4 they will be concatenated in the 
same way. This is the abuttal operation. For example, if the variable Total had the value 
37.4’, then Total’%’ would evaluate to ’37.4%’. Values that are not strings are first 
converted to strings before concatenation. The concatenation operators are listed in table 
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11.1.2 Arithmetic 


Character strings that are numbers (see page 61}) may be combined using the arithmetic 
operators listed in table B, The section on Numbers and Arithmetic (see page de- 
scribes numeric precision, the format of valid numbers, and the operation rules for arith- 
metic. Note that if an arithmetic result is shown in exponential notation, then it is likely 
that rounding has occurred. 


In binary classes (see page//1)) , the arithmetic operators will use binary arithmetic if both 
terms involved have values which are binary numbers. The section on Binary values and 
operations (see page {165) describes binary arithmetic. 





32 This can occur when the terms are syntactically distinct (such as a literal string and a symbol). 
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TABLE 4: Normal comparative operators 


= Equal (numerically or when padded, etc.). 











\= Not equal (inverse of =). 
> Greater than. 
< Less than. 





><,<> Greater than or less than (same as ”Not equal”). 





>=,\< Greater than or equal to, not less than. 





<=,\> Less than or equal to, not greater than. 
TABLE 5: Strict comparative operators 


== Strictly equal (identical). 





== Strictly not equal (inverse of ==). 





>> Strictly greater than. 





<< Strictly less than. 





>>=, \<< Strictly greater than or equal to, strictly not less than. 





<<=,\>> Strictly less than or equal to, strictly not greater than. 


11.1.3 Comparative 


The comparative operators compare two terms and return the value ’V’ if the result of 
the comparison is true, or 0’ otherwise. Two sets of operators are defined: the strict 
comparisons (listed in table 5) and the normal comparisons (listed in table 4). The strict 
comparative operators all have one of the characters defining the operator doubled. The 
*==", and ”\==” operators test for strict equality or inequality between two strings. Two 
strings must be identical to be considered strictly equal. Similarly, the other strict com- 
parative operators (such as ”>>” or ”<<”) carry out a simple left-to-right character-by- 
character comparison, with no padding of either of the strings being compared. If one 
string is shorter than, and is a leading sub-string of, another then it is smaller (less than) 
the other. Strict comparison operations are case sensitive, and the exact collating order 
may depend on the character set used for the implementation. §3 For all the other com- 
parative operators, if both the terms involved are numeric, 4a numeric comparison (in 
which leading zeros are ignored, etc.) is effected; otherwise, both terms are treated as 
character strings. For this character string comparison, leading and trailing blanks are 
ignored, and then the shorter string is padded with blanks on the right. The character 
comparison operation takes place from left to right, and is not case sensitive (that is, 
”Yes” compares equal to ”yes”). As for strict comparisons, the exact collating order may 
depend on the character set used for the implementation. 


b> > PD) ”» 


The equal and not equal operators (”=", , \= and ”\==”) may be used to compare 
two objects which are not strings for equality, if the implementation allows them to 
be compared (usually they will need to be of the same type). The strict operators test 





33 For example, in an ASCII or Unicode environment, the digits 0-9 are lower than the alphabetics, and lowercase alphabetics are 
higher than uppercase alphabetics. In an EBCDIC environment, lowercase alphabetics precede uppercase, but the digits are higher 
than all the alphabetics. 

34 That is, if they can be compared numerically without error. 
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TABLE 6: Boolean operators 


& And. Returns 1 if both terms are true. 





| Inclusive or. Returns 1 if either term is true. 





&& Exclusive or. Returns 1 if either (but not both) is true. 





Prefix Logical not. Negates; 1 becomes 0 and vice versa. 


whether the two objects are in fact the same object, 3 and the normal operators may 
provide a more relaxed comparison, if available to the implementation. 


In binary classes (see page {71}) , all the comparative operators will use binary arithmetic 
to effect the comparison if both terms involved have values which are binary numbers. 
In this case, there is no distinction between the strict and the normal comparative op- 
erators. The section on Binary values and operations (see page describes the binary 
arithmetic used for comparisons. 


11.1.4 Boolean 


A character string is taken to have the value “false” if it is 0’, and "true” if it is 1’. The 
logical operators take one or two such values (values other than ’0’ or’ are not allowed) 
and return ’0’ or’1’ as appropriate. The Boolean operators are listed in table 6, In binary 
classes (see page {71)) , the logical operators will act on all bits in the values if both terms 
involved have values which are boolean or integers. The section on Binary values and 
operations (see page describes this in more detail. 


11.1.5 Type 


Several of the operators already described can be used to carry out operations related to 
types. Specifically: 


« Any of the concatenation operators may be used for type concatenation, which con- 
catenates a type to a value. All three operators (blank, ”||’, and abuttal) have the 
same effect, which is to convert (see page 43) © the value to the type specified (if 
the conversion is not possible, an error is reported or an exception is signalled). 
The type must be on the left-hand side of the operator. Examples: 


String ”abc” 
int (atl) 
long 1 


Exception e 
InputStream myfile 


¢ A type on the left hand side of an operator that could be a prefix (+ ,- or \) type con- 
catenation after the prefix operator is applied to the right-hand operand, as though 
an explicit concatenation operator were placed before the prefix operator. 





35 Note that two distinct objects compared in this way may contain values (properties) that are identical, yet they will not compare 
equal as they are not the same object. 

36 In the reference implementation, the equals method is used for normal comparisons. Where not provided by a type, this is imple- 
mented by the Object class as a strict comparison. 

37 This is sometimes known as casting 
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For example: 

x=int -y 

means that -y is evaluated, and then the result is converted to int before being 
assigned to x. The "less than or equal” and the "greater than or equal” operators 
(’<=” and ”>=”) may be used with a type on either side of the operator, or on both 


sides. In this case, they test whether a value or type is a subclass of, or is the same 
as, a type, or vice versa. Examples: 


if i<=Object then say ’I is an Object’ 
if String>=i then say ’I is a String’ 
if String<=Object then say ’String is an Object’ 


The precedence of these operators is not affected by their being used with types as 
operands. 


11.2 Numbers 


The arithmetic operators above require that both terms involved be numbers; similarly 
some of the comparative operators carry out a numeric comparison if both terms are 
numbers. Numbers are introduced and defined in detail in the section on Numbers and 
arithmetic (see page . In summary, numbers are character strings consisting of one 
or more decimal digits optionally prefixed by a plus or minus sign, and optionally in- 
cluding a single period (”.”) which then represents a decimal point. A number may also 
have a power of ten suffixed in conventional exponential notation: an ”E” (uppercase 
or lowercase) followed by a plus or minus sign then followed by one or more decimal 
digits defining the power of ten. Numbers may have leading blanks (before and/or after 
the sign, if any) and may have trailing blanks. Blanks may not be embedded among the 
digits of a number or in the exponential part. Examples: 


742? 

t= 17.9" 
7127.0650’ 
?73e+128’ 

a oP IES? 
?Q00E+000’ 


Note that the sequence -17.9 (without quotes) in an expression is not simply a number. 
It is a minus operator (which may be prefix minus if there is no term to the left of it) 
followed by a positive number. The result of the operation will be a number. A whole 
number (see page in NetRExx is a number that has a zero (or no) decimal part. 


Implementation minimum: All implementations must support 9-digit arithmetic. In 
unavoidable cases this may be limited to integers only, and in this case the divide operator 
(°7”) must not be supported. If exponents are supported in an implementation, then they 
must be supported for exponents whose absolute value is at least as large as the largest 
number that can be expressed as an exact integer in default precision, i.e., 999999999. 





38 This could also have been written x=int (-y). 
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TABLE 7: Operator precedence 


Prefix operators +-\ 





Power operator ae 





Multiplication and division * and / 

















Addition and subtraction +- 

Concatenation (blank) || (abuttal) 
Comparative operators === >< <=>=<<\>> etc. 
And & 

Or, exclusive or | && 


11.3 Parentheses and operator precedence 


Expression evaluation is from left to right; this is modified by parentheses and by oper- 
ator precedence: 


¢ When parentheses are encountered, other than those that identify method calls 
(see page B7) , the entire sub-expression delimited by the parentheses is evaluated 
immediately when the term is required. 


¢ When the sequence 
term, operator, term, operator, term; 


is encountered, and operator, has a higher precedence than operator), then the 
operation (term, operator, term;) is evaluated first. The same rule is applied re- 
peatedly as necessary. Note, however, that individual terms are evaluated from left 
to right in the expression (that is, as soon as they are encountered). It is only the 
order of operations that is affected by the precedence rules. 


29499 


For example, ”*” (multiply) has a higher precedence than ”+” (add), so 3+2*5 will eval- 
uate to 13 (rather than the 25 that would result if strict left to right evaluation occurred). 
To force the addition to be performed before the multiplication the expression would be 
written (3+2)*5, where the first three tokens have been formed into a sub-expression by 
the addition of parentheses. The order of precedence of the operators is (highest at the 
top) is listed in table [7 


If, for example, the symbol a is a variable whose value is ’3’, and day is a variable with 
the value Monday’, then: 


at5 == 78? 

a-4x2 == ?-5? 

a/2 == 71.5’ 

a%2 == 7)? 

0.5**2 == °0.25’ 

(a+1)>7 == °Q’ /*x that is, False */ 
> 929? == °]? /x that is, True x/ 
7 %an?? == °Q’ /* that is, False x/ 
2 9\ ==)? sey 8? /* that is, True *x/ 
(at+1) *3=12 == 7)’ /* that is, True x/ 
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O77 2711? 
?O077’>>?11’ 
>abc’>>’ ab’ 
"If it is’ day 


day.substr (2,3) 


>I?day’!? 


== °)? /x that is, True x/ 


== °Q’ /x that is, False x/ 
== °)? /x that is, True x/ 
== °’If it is Monday’ 

== ond’ 

== °!Monday!’ 


Note: The NetRExx order of precedence usually causes no difficulty, as it is the same as 
in conventional algebra and other computer languages. There are two differences from 
some common notations; the prefix minus operator always has a higher priority than the 
power operator, and power operators (like other operators) are evaluated left-to-right. 


Thus 


—3x*x2 == 
—(24+1)**2 == 
2xk2**3 — 


9 /x not -9 x/ 
9 /* not -9 x/ 
64 /* not 256 x/ 


These rules were found to match the expectations of the majority of users when the REXx 
language was first designed, and NetRExx follows the same rules. 
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Clauses and Instructions 


Clauses (see page are recognized, and can usefully be classified, in the following 
order: 


Null clauses A clause that is empty or comprises only blanks, comments, and continua- 
tions is a null clause and is completely ignored by NetRExx (except that if it includes 
a comment it will be traced, if reached during execution). 


Note: A null clause is not an instruction, so (for example) putting an extra semi- 
colon after the then or else in an if instruction is not equivalent to putting a 
dummy instruction (as it would be in C or PL/I). The nop instruction is provided 
for this purpose. 


Assignments Single clauses within a class and of the form term=expression; are instruc- 

tions known as assignments (see page 7) . An assignment gives a variable, identi- 
fied by the term, a type or a new value. 
In just one context, where property assignments are expected (before the first 
method in a class), the ”=” and the expression may be omitted; in this case, the 
term (and hence the entire clause) will always be a simple non-numeric symbol 
which names the property 

Method call instructions A method call instruction (see page B8) is a clause within a 
method that comprises a single term that is, or ends in, a method invocation. 

Keyword instructions A keyword instruction consists of one or more clauses, the first 
of which starts with a non-numeric symbol which is not the name of a variable 
or property in the current class (if any) and is immediately followed by a blank, a 
semicolon (which may be implied by the end ofa line), a literal string, or an opera- 
tor (other than ”=”, which would imply an assignment). This symbol, the keyword, 
identifies the instruction. 

Keyword instructions control the external interfaces, the flow of control, and so 
on. Some keyword instructions (see page (do, if, loop, or select) can include 
nested instructions. 
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Assignments and Variables 


A variable is a named item whose value may be changed during the course of execution 
of a NetRExx program. The process of changing the value of a variable is called assigning 
a new Value to it. 


Each variable has an associated type, which cannot change during the execution of a 
program; therefore, the values assigned to a given variable must always have a type that 
can safely be assigned to that variable. 


Variables may be assigned a new value by the method or parse instructions, but the most 
common way of changing the value of a variable is by using an assignment instruction. 
Any clause within a class and of the form: 


assignment; 
where assignment is: 


term=expresston 


is taken to be an assignment instruction. The result of the expression becomes the new 
value of the variable named by the term to the left of the equals sign. When the term is 
simply a symbol, this is called the name of the variable. Example: 


/* Next Line gives FRED the value ’Frederic’ */ 
fred=’Frederic’ 


The symbol naming the variable cannot begin with a digit (0-9). 3 


Within a NetRExx program, variable names are not case-sensitive (for example, the 
names fred, Fred, and FRED refer to the same variable). Where public names are 
exposed (for example, the names of properties, classes, and methods, and in cross- 
reference listings) the case used for the name will be that used when the name was 
first introduced ("first” is determined statically by position in a program rather than 
dynamically). 


Similarly, the type of a NetRExx variable is determined by the type of the value of the 
expression that is first assigned to it. For subsequent assignments, it is an error to assign 
a value to a variable with a type mismatch unless the language processor can determine 





39 Without this restriction on the first character of a variable name, it would be possible to redefine a number, in that for example 
the assignment ”3=4;” would give a variable called ”3” the value ’4’. 

40 Since NetRExx infers the type of a variable from usage, substantial programs can be written without introducing explicit type 
declarations, although these are allowed. 
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that the value can be assigned safely to the type of the variable. 


In practice, this means that the types must match exactly, be a simplification, or both 
be ’well-known” types such as RExx, String, int, etc., for which safe conversions are 
defined. The possibilities are described in the section on Conversions (see page 43) . 


For example, if there are types (classes) called ibm.util.hex, RunKnown, and Window, 
then: 


hexy=ibm.util.hex(3) -- ’hexy’ has type ’ibm.util.hex’ 
rk=RunKnown () -- ?rk’ has type ’RunKnown’ 
fred=window(10, 20) -- ’fred’ has type ’Window’ 
s=”Los Lagos” -- ’s’ has type ’Rexx’ 

j=5 -- ?j’ has type ’Rexx’ 


The first three examples invoke the constructor method for the type to construct a value 
(an object). A constructor method always has the same name as the class to which it 
belongs, and returns a new value of that type. Constructor methods are described in 
detail in Methods and Constructors (see page B7)) . 


The last two examples above illustrate that, by default, the types of literal strings and 
numbers are NetRExx strings (type RExx) and so variables tend to be of type REXx. 
This simplifies the language and makes it easy to learn, as many useful programs can 
be written solely using the powerful RExx type. Potentially more efficient (though less 
human-oriented) primitive or built-in types for literals will be used in binary classes (see 
page {71}. If the examples above were in a binary class, then, in the reference implementa- 
tion, the types of s and j would have been java.lang.String and int respectively. 


A variable may be introduced ("declared”) without giving it an initial value by simply 
assigning a type to it: 


q=int 
r=Rexx 
f=java.io.File 


b>) 


Here, the expression to the right of the ”=” simply evaluates to a type with no value. 


13.1 The use and scope of variables 


NetRexx variables all follow the same rules of assignment, but are used in different con- 
texts. These are: 


Properties Variables which name the values (the data) owned by an object of the type 
defined by the class are called properties. When an object is constructed by the class, 
its properties are created and are initialized to either a default value (null or, for 
variables of primitive type, an implementation-defined value, typically 0) or to a 
value provided by the programmer. 

The attributes of properties can be changed by the properties instruction (see 
page [111]. For example, properties may also be constant, which means that they 





41 Implementations may provide for a stricter rule for assignment (where the types must be identical), controlled by the options 
instruction. 
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are initialized when the class is first loaded and do not change thereafter. 


Method arguments When a method is invoked, arguments may be passed to it. These 
method arguments are assigned to the variables named on the method instruction 
(see page 93) that introduces the method. 


Local variables Variables that are known only within a method are called local variables; 
each time a method is invoked a distinct set of local variables is available. Local 
variables are normally given an initial value by the programmer. If they are not, 
they are initialized to a default value (null or, for variables of primitive type, an 
implementation-defined value, typically 0). 


In order for types to be determined and type-checking to be possible at *compile-time’, 
and easily determined by inspection, the use and type of every variable is determined by 
its position in the program, not by the order in which assignments are executed. That is, 
variable typing is static. 


The visibility of a variable depends on its use. Properties are visible to all methods in a 
class; method arguments and local variables are only visible within the method in which 
they appear. In particular: 


¢ Within a class, properties have unique names (they cannot be overridden by 
method arguments or by local variables within methods); this avoids error-prone 
ambiguity. 


¢ Within a method, a method argument acts like a local variable (that is, it is in the 
same name-space as local variables, and can be assigned new values); it can be con- 
sidered to be a local variable that is assigned a value just before the body of the 
method is executed. There cannot be both a method argument and a local variable 
in a method with the same name. 


¢ Within methods, variables can take only one type, the type assigned to them when 
first encountered in the method (in a strict ”physical” sense, that is, as parsed from 
top to bottom of the program and from left to right on each line). Since methods 
tend to be small, there is no local scoping of variables inside the constructs within 
a method. 


Thus, in this example: 


method iszero(x) 
if x=0 then qualifier=’is zero’ 
else qualifier=’is not zero’ 
say ’The argument’ qualifier’.’ 


the variable qualifier is known throughout the method and hence has a known 
type and value when the say instruction is executed. 


To summarize: a symbol that names a variable in the current class either refers to a prop- 
erty (and in any use of it within the class refers to that property), or it refers to a variable 
that is unique within a method (and any use of the name within that method refers to 
the same variable). 





42 Unlike the block scoping of PL/I, C, or Java. 
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Note: A variable is just a name, or “handle” for a value. It is possible for more than one 
variable to refer to the same value, as in the program: 


first=’A string’ 
second=first 


Here, both variables refer to the same value. If that value is changeable then a change 
to the value referred to by one of the variable names would also be seen if the value is 
referred to by the other. For example, sub-values of a NetRExx string can be changed, 
using Indexed references (see page 61) , so a change to a sub-value of first would also be 
seen in an identical indexed reference to second. 


13.2 Terms on the left of assignments 


In an assignment instruction, the term to the left of the equals sign is most commonly 
a simple non-numeric symbol, which always names a variable in the current class. The 
other possibilities, as seen in the example below, are: 


1. The term is an indexed reference (see page 61) , to an existing variable that refers to 
a string of type REXX or an array (see page 62) . The variable may be in the current 
class, or be a property in a class named in the uses phrase of the class instruction 
for the current class. 

2. The term is a compound term (see page B2) that ultimately refers to a property (see 
above) in some class (which may be the current class). This property cannot be a 


constant. 
Examples: 
r=Rexx ’’ 
rl’? foo’ ]=’?’ -- indexed string assignment 
s=String[3] 
s[O]=’test’ -- array assignment 
Sample. value=1 -- property assignment 
this.value=1 -- property assignment 
super .vaLlue=1 -- property assignment 


The last two examples show assignments to a property in the current class or in a super- 
class of the current class, respectively. Note that references to properties in other classes 
must alway be qualified in some way (for example, by the prefix super.). The use of the 
prefix this. for properties in the current class is optional. 
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Indexed strings and Arrays 


Any NetRexx string (that is, a value of type RExx), has the ability to have sub-values, 
values (also of type RExx) which are associated with the original string and are indexed 
by an index string which identifies the sub-value. Any string with such sub-values is 
known as an indexed string. 


The sub-values of a NetRExx string are accessed using indexed references, where the 
name of a variable of type RExx is followed immediately by square brackets enclosing 
one or more expressions separated by commas: 4 


symbol’[’[expresston[, expression]...]’]’ 


It is important to note that the symbol that names the variable must be followed imme- 
diately by the ”[”, with no blank in between, or the construct will not be recognized as 
an indexed reference. The expressions (separated by commas) between the brackets are 
called the indexes to the string. These index expressions are evaluated in turn from left 
to right, and each must evaluate to a value is of type RExx or that can be converted to 
type RExx. 


The resulting index strings are taken “as-is” - that is, they must match exactly in content, 
case, and length for a reference to find a previously-set item. They may have any length 
(including the null string) and value (they are not constrained to be just those strings 
which are numbers, for example). 


If a reference does not find a sub-value, then a copy of the non-indexed value of the 
variable is used. Example: 


surname=’? Unknown’ -- default value 
surname[’ Fred’ ]=’Bloggs’ 
surname[’ Davy’ ]=’Jones’ 

try=’Fred’ 

say surname[try] surname[’Bert’ ] 


would say ’Bloggs Unknown’. 


When multiple indexes are used, they indicate accessing a hierarchy of strings. A single 
NetReExx string has a single set of indexes and subvalues associated with it. The sub- 
values, however, are also NetRExx strings, and so may in turn have indexes and sub- 
values. When more than one index is specified in an indexed reference, the indexes are 
applied in turn from left to right to each retrieved sub-value. 





43 The notations ’ [’ and ’]’ indicate square brackets appearing in the NetRExx program. 
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For example, in the sequence: 


X=7?? 
x[’ foo’, ’bar’]=’OK’ 
say x[’foo’, ’bar’] 
y=x[’ foo’ ] 

say y[’bar’] 


both say instructions would display the string ”OK”. Indexed strings may be used to set 
up “associative arrays’, or dictionaries, in which the subscript is not necessarily numeric, 
and thus offer great scope for the creative programmer. A useful application is to set up 
a variable in which the subscripts are taken from the value of one or more variables, so 
effecting a form of associative (content addressable) memory. Notes: 


1. A variable of type RExx must have been assigned a value before indexing is used on 
it. This is the value that is used as the default value whenever an indexed reference 
finds no sub-value. 

2. The indexes, and hence the sub-values, of a RExx object can be retrieved in turn 
using the over (see page 88) keyword of the loop instruction. 

3. The exists method (see page of the RExx class may be used to test whether an 
indexed reference has an explicitly-set value. 

4. Assigning null to an indexed reference (for example, the assignment switch[7]=null;) 
drops the sub-value; until set to a new value, any reference to the sub-value (in- 
cluding use of the exists method) will return the same result as when it had never 
been set. 


14.1 Arrays 


In addition to indexed strings, NetRExx also includes the concept of fixed-size arrays, 
which may be used for indexing values of any type (including strings). 


Arrays are used with the same syntax and in the same manner as indexed strings, but 
with important differences that allow for compact implementations and access to equiv- 
alent data structures constructed using other programming languages: 


1. The indexes for arrays must be whole numbers that are zero or positive. There will 
usually be an implementation restriction on the maximum value of the index (typ- 
ically 999999999 or higher). 

2. The elements of an array are considered to be ordered; the first element has index 
0, the second 1, and so on. 


3. An array is of fixed size; it must be constructed before use. 


4, Variables that are assigned arrays can only be assigned arrays (of the same dimen- 
sion, see below) in the future. That is, being an array changes the type of a value; it 
becomes a dimensioned type (see page 28) . 


Array references use the NetRExx indexed reference syntax defined above. The same 
syntax is used for constructing arrays, except that the symbol before the left bracket 
describes a type (and hence may be qualified by a package name). The expression or 
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expressions between the brackets indicate the size of the array in each dimension, and 
must be a positive whole number or zero: 


arg=String[4] -- makes an array for four Strings 
arg=java.io.File[4] -- makes an array for four Files 
i=int[3] -- makes an array for three ’int’s 


(Another way of describing this is that array constructors look just like other object con- 
structors, except that brackets are used instead of parentheses.) 


Once an array has been constructed, its elements can be referred to using brackets and 
expressions, as before: 


i[2]=3 -- sets the ’2’-indexed value of ’7’ 
j=i[2] -- sets ’j’ to the ’2’-indexed value of ’7’ 


Regular multiple-dimensioned arrays may be constructed and referenced by using mul- 
tiple expressions within the brackets: 


i=int[2,3] -- makes a 2x3 array of ’int’ type objects 
1[1,2]=3 -- sets the ’1,2’-indexed value of ’7’ 
j=i[1,2] -- sets ’j’ to the °’1,2’-indexed value of ’7’ 


As with indexed strings, when multiple indexes are used, they indicate accessing a hier- 
archy of arrays (the underlying model is therefore of a hierarchy of single-dimensioned 
arrays). When more than one index is specified in an indexed reference to an array, the 
indexes are applied in turn from left to right to each array. 


As described in the section on Types (see page 27) , the type of a variable that refers to an 
array can be set (declared) by assignment of the type with array notation that indicates 
the dimension of an array without any sizes: 


k=int[] -- one-dimensional array of ’int’ objects 
m=float[,,] -- 3-dimensional array of ’float’ objects 


The same syntax is also used when describing an array type in the arguments of a method 
instruction or when converting types. For example, after: 


gg=char[] ”Horse” 


the variable gg has as its value an array of type char[] containing the five characters H, 
o, r, s, and e. 


14.1.1 Array initializers 


An array initializer is a simple term which is recognized if it does not immediately follow 
(abut) a symbol, and has the form 4 


>[’?expression[,expression]...’]’ 


An array initializer therefore comprises a list of one or more expressions, separated by 
commas, within brackets. When an array initializer is evaluated, the expressions are eval- 





44 The notations ’ [’ and ’]” indicate square brackets appearing in the NetRExx program. 
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uated in turn from left to right, and all must result in a value. An array is then con- 
structed, with a number of elements equal to the number of expressions in the list, with 
each element initialized by being assigned the result of the corresponding expression. 


The type of the array is derived by adding one dimension to the type of the result of the 
first expression in the list, where the type of that expression is determined using the same 
rules as are used to select the type of a variable when it is first assigned a value(see page 
57). All the other expressions in the list must have types that could be assigned to the 
chosen type without error. 


For example, in 


varl=[’aa’, ’bb’, ’cc’] 
var2=[char ’a’, ’b’, ’c’] 
var3=[String ’a’, ’bb’, ’c’] 
var4=[1, 2, 3, 4, 5, 6] 
var5=[[1,2], [3,4]] 


the types of the variables would be RExx[], char[], String[], RExx[], and RExx[,] re- 
spectively. In a binary class in the reference implementation, the types would be String[], 
char[], String[], int[], and int[,]. 


Array initializers are most useful for initializing properties and variables, but like other 
simple terms, they may start a compound term. 


So, for example 
say [1,1,1,1].length 


would display 4. Note that an array of length zero cannot be constructed with an ar- 
ray initializer, as its type would be undefined. An explicitly typed array constructor (for 
example, int[0]) must be used. 
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Keyword Instructions 


A keyword instruction is one or more clauses, the first of which starts with a keyword 
that identifies the instruction. Some keyword instructions affect the flow of control; the 
remainder just provide services to the programmer. Some keyword instructions (do, 7f, 
loop, or select) can include nested instructions. Appendix A (see page includes 
an example of a NetRExx program using many of the instructions available. As can be 
deduced from the syntax rules described earlier, a keyword instruction is recognized 
only if its keyword is the first token in a clause, and if the second token is not an ”=” 
character (implying an assignment). It would also not be recognized if the second token 
started with ”(’,”[’; or ”.” (implying that the first token starts a term). Further, if a current 
local variable, method argument, or property has the same name as a keyword then the 
keyword will not be recognized. This important rule allows NetRExx to be extended 
with new keywords in the future without invalidating existing programs. 


Thus, for example, this sequence in a program with no say variable: 


say ’Hello’ 
say(’1’) 
say=3 

say ’Hello’ 


would be a say instruction, a call to some say method, an assignment to a say variable, 
and an error. In NetRExx, therefore, keywords are not reserved; they may be used as the 
names of variables (though this is not recommended, where known in advance). Certain 
other keywords, known as sub-keywords, may be known within the clauses of individual 
instructions - for example, the symbols to and while in the loop instruction. Again, 
these are not reserved; if they had been used as names of variables, they would not be 
recognized as sub-keywords. Blanks adjacent to keywords have no effect other than that 
of separating the keyword from the subsequent token. For example, this applies to the 
blanks next to the sub-keyword while in 


loop while a=3 


Here at least one blank was required to separate the symbols forming the keywords and 
the variable name, a. However the blank following the while is not necessary in 


loop while ’Me’=a 


though it does aid readability. 
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Annotation instruction 


An annotation starts with an @ (commercial at sign) and is passed through unchanged 
to the generated Java source. To interpret a program with an annotation is an error. 
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Class instruction 


class name [visibility] [modifier] [binary] [deprecated] 
[extends classname | 
[uses useslist ] 
[implements interfacelist]; 


where visibility is one of: 


private 
public 
shared 


and modifier is one of: 


abstract 
adapter 
final 
interface 


and useslist and interfacelist are lists of one or more classnames, 
separated by commas. 


The class instruction is used to introduce a class, as described in the sections Types and 
Classes (see page 27) and Program structure (see page , and define its attributes. The 
class must be given a name, which must be different from the name of any other classes 
in the program. The name, which must be a non-numeric symbol, is known as the short 
name of the class. 


A classname can be either the short name ofa class (if that is unambiguous in the context 
in which it is used), or the qualified name of the class - the name of the class prefixed 
by a package name and a period, as described under the package instruction (see page 
107). 


The body of the class consists of all clauses following the class instruction (if any) until 
the next class instruction or the end of the program. 


The visibility, modifier, and binary keywords, and the extends, uses, and implements 
phrases, may appear in any order. 
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17.1 Visibility 


Classes may be public, private, or shared: 


« A public class is visible to (that is, may be used by) all other classes. 

* A private class is visible only within same program and to classes in the same pack- 
age (see page 

« A shared class is also visible only within same program and to classes in the same 
package. 4 


A program may have only one public class, and if no class is marked public then the first 
is assumed to be public (unless it is explicitly marked private). 


17.2. Modifier 


Most classes are collections of data (properties) and the procedures that can act on that 
data (methods); they completely implement a datatype (type), and are permitted to be 
subclassed. These are called standard classes. The modifier keywords indicate that the 
class is not a standard class - it is special in some way. Only one of the following modifier 
keywords is allowed: 


abstract An abstract class does not completely implement a datatype; one or more of the 
methods that it defines (or which it inherits from classes it extends or implements) 
is abstract - that is, the name of the method and the types of its arguments are 
defined, but no instructions to implement the method are provided. 
Since some methods are not provided, an object cannot be constructed from an ab- 
stract class. Instead, the class must be extended and any missing methods provided. 
Such a subclass can then be used to construct an object. 
Abstract classes are useful where many subclasses can share common data or meth- 
ods, but each will have some unique attribute or attributes (data and/or methods). 
For example, some set of geometric objects might share dimensions in X and Y, yet 
need unique methods for calculating the area of the object. 

adapter An adapter class is a class that is guaranteed to implement all unimplemented 
abstract methods of its superclasses and interface classes that it inherits or lists as 
implemented on the class instruction. 
If any unimplemented methods are found, they will be automatically generated by 
the language processor. Methods generated in this way will have the same visibil- 
ity and signature as the abstract method they implement, and if a return value is 
expected then a default value is returned (as for the initial value of variables of the 
same type: that is, null or, for values of primitive type, an implementation-defined 
value, typically 0). Other than possibly returning a value, these methods are empty; 
that is, they have no side-effects. 
An adapter class provides a concrete representation of its superclasses and the in- 
terface classes it implements. As such, it is especially useful for implementing event 





45 The shared keyword on the class instruction means exactly the same as the keyword private, and is accepted for consistency 
with the other meanings of shared. 
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handlers and the like, where only a small number of event-handling methods are 
needed but many more might be specified in the interface class that describes the 
event model. £4 
An adapter class cannot have any abstract methods. 

final A final class is considered to be complete; it cannot be subclassed (extended), and 
all its methods are considered complete. 4 

interface An interface class is an abstract class that contains only abstract method def- 
initions and/or constants. That is, it defines neither instructions that implement 
methods nor modifiable properties, and hence cannot be used to construct an ob- 
ject. 
Interface classes are used by classes that claim to implement them (see the implements 
keyword, described below). The difference between abstract and interface classes 
is that the former may have methods which are not abstract, and hence can only 
be subclassed (extended), whereas the latter are wholly abstract and may only be 
implemented. 


17.3 Binary 


The keyword binary indicates that the class is a binary class. In binary classes, literal 
strings and numeric symbols are assigned native string or binary (primitive) types, 
rather than NetRExx types, and native binary operations are used to implement oper- 
ators where possible. When binary is not in effect (the default), terms in expressions 
are converted to NetRExx types before use by operators. The section Binary values and 
operations (see page describes the implications of binary classes in detail. 


Individual methods in a class which is not binary can be made into binary methods using 
the binary keyword on the method instruction (see page 3) . 


17.4 Deprecated 


The keyword deprecated indicates that the class is deprecated, which implies that a better 
alternative is available and documented. A compiler can use this information to warn of 
out-of-date or other use that is not recommended. 


17.5 Extends 


Classes form a hierarchy, with all classes (except the top of the tree, the Object class) 
being a subclass of some other class. The extends keyword identifies the classname of 
the immediate superclass of the new class - that is, the class immediately above it in the 
hierarchy. If no extends phrase is given, the superclass is assumed to be Object (or null, 
in the case where the current class is Object). 





46 For example, see the ’Scribble” sample in the NetRExx package. 

47 This modifier is provided for consistency with other languages, and may allow compilers to improve the performance of classes 
that refer to the final class. In many cases it will reduce the reusability of the class, and hence should be avoided. 

48 In the reference implementation, java.lang.Object. 
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17.6 Uses 


The uses keyword introduces a list of the names of one or more classes that will be used 
as a source of constant (or static) properties and/or methods. 


When a term (see page B1)) starts with a symbol, method call, or indexed reference that 
is not known in the current context, each class in the useslist and its superclasses are 
searched (in the order specified in the useslist) for a constant or static method or property 
that matches the item. If found, the method or property is used just as though explicitly 
qualified by the name of the class in which it was found. 


The uses mechanism affects only the syntax of terms in the current class; it is not inher- 
ited by subclasses of the current class. 


17.7 Implements 


The implements keyword introduces a list of the names of one or more interface classes 
(see above). These interface classes are then known to (inherited by) the current class, in 
the order specified in the interfacelist. Their methods (which are all abstract) and con- 
stant properties act as though part of the current class, unless they are overridden (hid- 
den) by a method or constant of the same name in the current class. 


If the current class is not an interface class then it must implement (provide non-abstract 
methods for) all the methods inherited from the interface classes in the implements list. 


Interface classes, therefore, can be used to: 


1. Define a common set of methods (possibly with associated constants) that will be 
implemented by other classes. 


2. Conveniently package collections of constants for use by other classes. 


The implements list may not include the superclass of the current class. 


72 


18 





Do instruction 


do [label name] [protect term] [binary]; 
instructtonlist 
[catch [vare =] exception; 
instructtionlist]... 
[finally[; ] 
instructtionlist] 
end [name]; 


where name is a non-numeric symbol 


and instructionlist is zero or more instructions 


The do instruction is used to group instructions together for execution; these are exe- 
cuted once. The group may optionally be given a label, and may protect an object while 
the instructions in the group are executed; exceptional conditions can be handled with 
catch and finally. 


The most common use of do is simply for treating a number of instructions as group. 


Example: 


/x The two instructions between DO and END will both x/ 
/x be executed if A has the value 3. */ 
if a=3 then do 

a=at+2 

say ’Smile!’ 

end 


Here, only the first instructionlist is used. This forms the body of the group. 


The instructions in the instructionlists may be any assignment, method call, or keyword 
instruction, including any of the more complex constructions such as loop, if, select, 
and the do instruction itself. 


18.0.1 Label phrase 


If Label is used to specify a name for the group, then a leave which specifies that name 
may be used to leave the group, and the end that ends the group may optionally specify 
the name of the group for additional checking. 
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Example: 


do label sticky 
x=ask 
if x=’quit’ then leave sticky 
say ’X was’ xX 
end sticky 


18.0.2 Protect phrase 


If protect is given it must be followed by a term that evaluates to a value that is not just 
a type and is not of a primitive type; while the do construct is being executed, the value 
(object) is protected - that is, all the instructions in the do construct have exclusive access 
to the object. 


Both label and protect may be specified, in any order, if required. 


18.0.3 Exceptions in do groups 


Exceptions that are raised by the instructions within a do group may be caught using one 
or more catch clauses that name the exception that they will catch. When an exception 
is caught, the exception object that holds the details of the exception may optionally be 
assigned to a variable, vare. 


Similarly, a finally clause may be used to introduce instructions that will always be 
executed at the end of the group, even if an exception is raised (whether caught or not). 


The Exceptions section (see page has details and examples of catch and finally. 
18.0.4 Binary 


A group of one or more statements in a do binary group will follow the semantics of 
binary statements in binary classes or methods; the scope is limited to the do binary 


group. 
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Exit instruction 


exit [expression]; 


exit is used to unconditionally leave a program, and optionally return a result to the 
caller. The entire program is terminated immediately. 


If an expression is given, it is evaluated and the result of the evaluation is then passed back 
to the caller in an implementation-dependent manner when the program terminates. 
Typically this value is expected to be a small whole number; most implementations will 
accept values in the range 0 through 250. If no expression is given, a default result (which 
depends on the implementation, and is typically zero) is passed back to the caller. 


Example: 

j=3 

exit j*4 

/* Would exit with the value ’12’ x/ 


”Running off the end” of a program is equivalent to the instruction return;. In the case 
where the program is simply a stand-alone application with no class or method instruc- 
tions, this has the same effect as exits, in that it terminates the whole program and returns 
a default result. 
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If instruction 


if expression[;] 
then[;] instruction 
[else[;] tnstruction] 


The if construct is used to conditionally execute an instruction or group of instructions. 
It can also be used to select between two alternatives. The expression is evaluated and 
must result in either 0 or 1. If the result was 1 (true) then the instruction after the then 
is executed. If the result was 0 (false) and an else was given then the instruction after 
the else is executed. Example: 


if answer=’Yes’ then say ’OK!’ 
else say ’Why not?’ 


Remember that if the else clause is on the same line as the last clause of the then part, 
then you need a semicolon to terminate that clause. Example: 


if answer=’Yes’ then say ’OK!’; else say ’Why not?’ 


The else binds to the nearest then at the same level. This means that any 7 f that is used as 
the instruction following the then in an if construct that has an else clause, must itself 
have an else clause (which may be followed by the dummy instruction, nop). Example: 


if answer=’Yes’ then if name=’Fred’ then say ’OK, Fred.’ 
else say ’OK.’ 
else say ’Why not?’ 


To include more than one instruction following then or else, use a grouping instruction 
(do, loop, or select). Example: 


if answer=’Yes’ then do 
say ’Line one of two’ 
say ’Line two of two’ 
end 


In this instance, both say instructions are executed when the result of the if expression 
is 1. 

Multiple expressions, separated by commas, can be given on the if clause, which then 
has the syntax: 
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if expression[, expression]... [3] 


In this case, the expressions are evaluated in turn from left to right, and if the result of any 
evaluation is 1 then the test has succeeded and the instruction following the associated 
then clause is executed. If all the expressions evaluate to 0 and an else was given then 
the instruction after the else is executed. 


Note that once an expression evaluation has resulted in 1, no further expressions in the 
clause are evaluated. So, for example, in: 


-- assume ’name’ jis a string 
if name=null, name=’’ then say ’Empty’ 


then if name does not refer to an object it will compare equal to null and the say instruc- 
tion will be executed without evaluating the second expression in the if clause. 


Notes: 


1. An instruction may be any assignment, method call, or keyword instruction, in- 
cluding any of the more complex constructions such as do, loop, select, and the 
if instruction itself. A null clause is not an instruction, however, so putting an extra 
semicolon after the then or else is not equivalent to putting a dummy instruction. 
The nop instruction is provided for this purpose. 

2. The keyword then is treated specially, in that it need not start a clause. This allows 
the expression on the if clause to be terminated by the then, without a ”;” being 
required - were this not so, people used to other computer languages would be 
inconvenienced. Hence the symbol then cannot be used as a variable name within 


the expression. 
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Import instruction 


import name; 


where name is one or more non-numeric symbols separated by periods, 
with an optional trailing period. 


The import instruction is used to simplify the use of classes from other packages. If a 
class is identified by an import instruction, it can then be referred to by its short name, 
as given on the class instruction (see page 69) , as well as by its fully qualified name. 


There may be zero or more import instructions in a program. They must precede any 
class instruction (or any instruction that would start the default class). 


In the following description, a package name names a package as described under the 
package instruction (see page {107). The import name must be one of: 


« A qualified class name, which is a package name immediately followed by a period 
which is immediately followed by a short class name - in this case, the individual 
class identified is imported. 

« A package name - in this case, all the classes in the specified package are imported. 
The name may have a trailing period. 

- A partial package name (a package name with one or more parts omitted from the 
right, indicated by a trailing period after the parts that are present) - in this case, 
all classes in the package hierarchy below the specified point are imported. 


Examples: 


import java.lang.String 
import java. lang 
import java. 


The first example above imports a single class (which could then be referred to simply as 
*String”). The second example imports all classes in the ”java.lang” package. The third 
example imports all classes in all the packages whose name starts with ”java.”. 


When a class is imported explicitly, for example, using 
import java.awt.List 


this indicates that the short name of the class (List, in this example) may be used 
to refer to the class unambiguously. That is, using this short name will not report an 
ambiguous reference warning (as it would without the import instruction, because a 


79 


02 


java.util.List class was added in Java 1.2). 
It follows that: 


¢ Two classes imported explicitly cannot have the same short name. 
* No class in a program being compiled can have the same short name as a class that 
is imported explicitly. 


because in either of these situations a use of the short name would be ambiguous. 


Note also that an explicit import does not import the minor or dependent classes associ- 
ated with a name; they each require their own explicit import (unless the entire package 
is imported). 


In the reference implementation, the fundamental NetRExx and Java package hierarchies 
are automatically imported by default, as though the instructions: 


import netrexx. lang. 
import java.lang. 
import java.io. 
import java.util. 
import java.net. 
import java.awt. 
import java.applet. 
import javax.swing 


had been executed before the program begins. In addition, classes in the current (working) 
directory are imported if no package instruction is specified. If a package instruction is 
specified then all classes in that package are imported. 
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Iterate instruction 


iterate [name]; 


where name iS a non-numeric symbol. 


iterate alters the flow of control within a loop construct. It may only be used in the 
body (the first instructionlist) of the construct. 


Execution of the instruction list stops, and control is passed directly back up to the loop 
clause just as though the last clause in the body of the construct had just been executed. 
The control variable (if any) is then stepped (iterated) and termination conditions tested 
as normal and the instruction list is executed again, unless the loop is terminated by the 
Loop clause. 


If no name is specified, then iterate will step the innermost active loop. 


If a name is specified, then it must be the name of the label, or control variable if there 
is no label, of a currently active loop (which may be the innermost), and this is the loop 
that is iterated. Any active do, loop, or select constructs inside the loop selected for 
iteration are terminated (as though by a leave instruction). 


Example: 


loop i=1 to 4 
if i=2 then iterate i 
say i 
end 
/x Would display the numbers: 1, 3, 4 *x/ 


Notes: 


1. A loop is active if it is currently being executed. If a method (even in the same 
class) is called during execution of a loop, then the loop becomes inactive until the 
method has returned. iterate cannot be used to step an inactive loop. 

2. The name symbol, if specified, must exactly match the label (or the name of the 
control variable, if there is no label) in the Loop clause in all respects except case. 
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Leave instruction 


leave [name]; 


where name is a non-numeric symbol. 


leave causes immediate exit from one or more do, loop, or select constructs. It may 
only be used in the body (the first instructionlist) of the construct. 


Execution of the instruction list is terminated, and control is passed to the end clause of 
the construct, just as though the last clause in the body of the construct had just been 
executed or (if a loop) the termination condition had been met normally, except that on 
exit the control variable (if any) will contain the value it had when the leave instruction 
was executed. 


If no name is specified, then leave must be within an active loop and will terminate the 
innermost active loop. 


If a name is specified, then it must be the name of the label (or control variable for a 
loop with no label), of a currently active do, Loop, or select construct (which may be 
the innermost). That construct (and any active constructs inside it) is then terminated. 
Control then passes to the clause following the end clause that matches the do, loop, or 
select clause identified by the name. 


Example: 


loop i=1 to 5 
say ji 
if i=3 then leave 
end i 
/x Would display the numbers: 1, 2, 3 x/ 


Notes: 


1. If any construct being left includes a finally clause, the instructionlist following 
the finally will be executed before the construct is left. 

2. Ado, loop, or select construct is active ifit is currently being executed. Ifa method 
(even in the same class) is called during execution of an active construct, then the 
construct becomes inactive until the method has returned. leave cannot be used 
to leave an inactive construct. 

3. The name symbol, if specified, must exactly match the label (or the name of the 
control variable, for a loop with no label) in the do, loop, or select clause in all 
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respects except case. 
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Loop instruction 


loop [label name] [protect termp] [repetitor] [conditional]; 
instructtonlist 
[catch [vare =] exception; 
instructtonlist]... 
[finally[; ] 
instructtionlist] 
end [name]; 


where repetitor is one of: 


varc = expri [to exprt] [by exprb] [for exprf] 
varo over termo 

for exprr 

forever 


and conditional is either of: 


while exprw 
until expru 


and name is a non-numeric symbol 
and instructionlist is zero or more instructions 


and expri, exprt, exprb, exprf, exprr, exprw, and expru are expressions. 


The loop instruction is used to group instructions together and execute them repeti- 
tively. The loop may optionally be given a label, and may protect an object while the 
instructions in the loop are executed; exceptional conditions can be handled with catch 
and finally. Loop is the most complicated of the NetRExx keyword instructions. It can 
be used as a simple indefinite loop, a predetermined repetitive loop, as a loop with a 
bounding condition that is recalculated on each iteration, or as a loop that steps over the 
contents of a collection of values. 
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24.1 Syntax notes: 


¢ The label and protect phrases may be in any order. They must precede any repeti- 
tor or conditional. 

¢ The first instructionlist is known as the body of the loop. 

¢ The to, by, and for phrases in the first form of repetitor may be in any order, if 
used, and will be evaluated in the order they are written. 

¢ Any instruction allowed in a method is allowed in an instructionlist, including as- 
signments, method call instructions, and keyword instructions (including any of 
the more complex constructions such as if, do, select, or the loop instruction 
itself). 

¢ If for or forever start the repetitor and are followed by an ”=” character, they are 
taken as control variable names, not keywords (as for assignment instructions). 

¢ The expressions expri, exprt, exprb, or exprf will be ended by any of the keywords 
to, by, for, while, or until (unless the word is the name of a variable). 

¢ The expressions exprw or expru will be ended by either of the keywords while or 
until (unless the word is the name of a variable). 


24.2 Indefinite loops 


If neither repetitor nor conditional are present, or the repetitor is the keyword forever, 
then the loop is an indefinite loop. It will be ended only when some instruction in the 
first instructionlist causes control to leave the loop. 


Example: 


/x This displays ”Go caving!” at least once x/ 
loop forever 

say ’Go caving!’ 

if ask=’’ then leave 

end 


24.3 Bounded loops 


If a repetitor (other than forever) or conditional is given, the first instructionlist forms 
a bounded loop, and the instruction list is executed according to any repetitor phrase, 
optionally modified by a conditional phrase. 


Simple bounded loops When the repetitor starts with the keyword for, the expression 
exprr is evaluated immediately (with 0 added, to effect any rounding) to give a 
repetition count, which must be a whole number that is zero or positive. The loop 
is then executed that many times, unless it is terminated by some other condition. 
Example: 


/* This displays ”Hello” five times x*/ 
loop for 5 
say ’Hello’ 
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end 


» 


A controlled loop begins with an assignment, which can be identified by the 
that follows the name of a control variable, varc. The control variable is assigned an 
initial value (the result of expri, formatted as though 0 had been added) before the 
first execution of the instruction list. The control variable is then stepped (by adding 
the result of exprb) before the second and subsequent times that the instruction list 
is executed. 
The name of the control variable, varc, must be a non-numeric symbol that names 
an existing or new variable in the current method or a property in the current class 
(that is, it cannot be element of an array, the property of a superclass, or a more 
complex term). It is further restricted in that it must not already be used as the name 
of a control variable or label in a loop (or do or select construct) that encloses the 
new loop. 
The instruction list in the body of the loop is executed repeatedly while the end 
condition (determined by the result of exprt) is not met. If exprb is positive or zero, 
then the loop will be terminated when varc is greater than the result of exprt. If neg- 
ative, then the loop will be terminated when varc is less than the result of exprt. The 
expressions exprt and exprb must result in numbers. They are evaluated once only 
(with 0 added, to effect any rounding), in the order they appear in the instruction, 
and before the loop begins and before expri (which must also result in a number) 
is evaluated and the control variable is set to its initial value. 
The default value for exprb is 1. If no exprt is given then the loop will execute in- 
definitely unless it is terminated by some other condition. Example: 
Controlled bounded loops loop i=3 to -2 by -1 

say i 

end 
/* Would display: 3, 2, 1, 0, -1, -2 x/ 
Note that the numbers do not have to be whole numbers: Example: 


x=0.3 
loop y=x to x+4 by 0.7 
Say y 
end 
/x Would display: 0.3, 1.0, 1.7, 2.4, 3.1, 3.8 x/ 


The control variable may be altered within the loop, and this may affect the itera- 
tion of the loop. Altering the value of the control variable in this way is normally 
considered to be suspect programming practice, though it may be appropriate in 
certain circumstances. Note that the end condition is tested at the start of each it- 
eration (and after the control variable is stepped, on the second and subsequent 
iterations). It is therefore possible for the body of the loop to be skipped entirely 
if the end condition is met immediately. The execution of a controlled loop may 
further be bounded by a for phrase. In this case, exprf must be given and must 
evaluate to a non-negative whole number. This acts just like the repetition count 
in a simple bounded loop, and sets a limit to the number of iterations around the 
loop if it is not terminated by some other condition. 

exprf is evaluated along with the expressions exprt and exprb. That is, it is evaluated 
once only (with 0 added), when the loop instruction is first executed and before 
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the control variable is given its initial value; the three expressions are evaluated in 
the order in which they appear. Like the to condition, the for count is checked at 
the start of each iteration, as shown in the programmer's (see page 90) model:ea.. 
Example: 


loop y=0.3 to 4.3 by 0.7 for 3 
say y 
end 
/* Would display: 0.3, 1.0, 1.7 */ 


In a controlled loop, the symbol that describes the control variable may be specified 
on the end clause (unless a label is specified, see below). NetRExx will then check 
that this symbol exactly matches the varc of the control variable in the Loop clause 
(in all respects except case). If the symbol does not match, then the program is in 
error - this enables the nesting of loops to be checked automatically. Example: 


loop k=1 to 10 


end k /*x Checks this is the END for K loop x/ 


Note: The values taken by the control variable may be affected by the numer ‘ic set- 
tings, since normal NetRexx arithmetic rules apply to the computation of stepping 
the control variable. 


Over When the second token of the repetitor is the keyword over, the control variable, 
varo, is used to work through the sub-values in the collection of indexed strings 
identified by termo. In this case, the loop instruction takes a “snapshot” of the in- 
dexes that exist in the collection at the start of the loop, and then for each iteration 
of the loop the control variable is set to the next available index from the snapshot. 
The number of iterations of the loop will be the number of indexes in the collection, 
unless the loop is terminated by some other condition. Example: 


mycoll=’’ 
mycoll[’?Tom’ ]=1 
mycoLl[’Dick’ ]=2 
mycoll[’Harry’]=3 
loop name over mycoll 

say mycoll[name] 

end 
/* might display: 3, 1, 2 x/ 
Notes: 

1. The order in which the values are returned is undefined; all that is known is 
that all indexes available when the loop started will be recorded and assigned 
to varo in turn as the loop iterates. 

2. The same restrictions apply to varo as apply to varc, the control variable for 
controlled loops (see above). 

3. Similarly, the symbol varo may be used as a name for the loop and be specified 
on the end clause (unless a label is specified, see below). 

In the reference implementation, the over form of repetitor may also be used to step 
though the contents of any object that is of a type that is a subclass of java.util. Dictionary, 
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such as an object of type java.util. Hashtable. In this case, termo specifies the dictio- 
nary, and a snapshot (enumeration) of the keys to the Dictionary is taken at the start 
of the loop. Each iteration of the loop then assigns a new key to the control variable 
varo which must be (or will be given, if it is new) the type java.lang.Object. 
Conditional phrases Any of the forms of loop syntax can be followed by a conditional 

phrase which may cause termination of the loop. 
If while is specified, exprw is evaluated, using the latest values of all variables in 
the expression, before the instruction list is executed on every iteration, and after 
the control variable (if any) is stepped. The expression must evaluate to either 0 or 
1, and the instruction list will be repeatedly executed while the result is 1 (that is, 
the loop ends if the expression evaluates to 0). Example: 
loop i=1 to 10 by 2 while i<6 

say i 

end 
/x Would display: 1, 3, 5 x/ 
If until is specified, expru is evaluated, using the latest values of all variables in 
the expression, on the second and subsequent iterations, and before the control 
variable (if any) is stepped. 4 The expression must evaluate to either 0 or 1, and 
the instruction list will be repeatedly executed until the result is 1 (that is, the loop 
ends if the expression evaluates to 1). Example: 
loop i=1 to 10 by 2 until i>6 

say ji 

end 
/* Would display: 1, 3, 5, 7 */ 


Note that the execution of loops may also be modified by using the iterate or leave 
instructions. 


24.4 Label phrase 


The label phrase may used to specify a name for the loop. The name can then optionally 
be used on 


* a leave instruction, to specify the name of the loop to leave 

* an iterate instruction, to specify the name of the loop to be iterated 

* the end clause of the loop, to confirm the identity of the loop that is being ended, 
for additional checking. 


Example: 


loop label pooks i=1 to 10 
loop label hill while j<3 


if a=b then leave pooks 





50 Thus, it appears that the until condition is tested after the instruction list is executed on each iteration. However, it is the loop 
clause that carries out the evaluation. 
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end hilt 
end pooks 


In this example, the leave instruction leaves both loops. 


If a label is specified using the Label keyword, it overrides any name derived from the 
control variable name (if any). That is, the variable name cannot be used to refer to the 
loop if a label is specified. 


24.5 Protect phrase 


The protect phrase may used to specify a term, termp, that evaluates to a value that is 
not just a type and is not of a primitive type; while the Loop construct is being executed, 
the value (object) is protected - that is, all the instructions in the loop construct have 
exclusive access to the object. Example: 


loop protect myobject while a<b 


end 


Both label and protect may be specified, in any order, if required. 


24.6 Exceptions in loops 


Exceptions that are raised by the instructions within a loop construct may be caught 
using one or more catch clauses that name the exception that they will catch. When 
an exception is caught, the exception object that holds the details of the exception may 
optionally be assigned to a variable, vare. 


Similarly, a finally clause may be used to introduce instructions that will always be 
executed when the loop ends, even if an exception is raised (whether caught or not). 


The Exceptions section (see page has details and examples of catch and finally. 


24.7 Programmer’s model - how a typical loop is executed 


This model forms part of the definition of the loop instruction. For the following loop: 


loop varc = expri to exprt by exprb while exprw 
instruction list 


end 
NetRexx will execute the following: 


Stempt=exprt+0 /* (Svariables are internal and * / 
Stempb=exprb+0 /* are not accessible.) x / 
varc=exprit+0 
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Transfer control to the point identified as $start: 


$loop: 
/* An UNTIL expression would be tested here, with: x/ 
/* if expru then leave */ 
varc=varc + Stempb 

$start: 
if varc > $tempt then leave /x* leave quits a loop «/ 
/*x A FOR count would be checked here x/ 


if \ exprw then leave 
instruction list 


Transfer control to the point identified as $loop: 
Notes: 


1. This example is for exprb >= 0. For a negative exprb, the test at the start point of the 
loop would use ”<” rather than ”>”. 

2. The upwards transfer of control takes place at the end of the body of the loop, im- 
mediately before the end clause (or any catch or finally clause). The end clause 
is only reached when the loop is finally completed. 
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Method instruction 


method name[(Larglist])] 
[visibility] [modifier] [protect] [binary] [deprecated] 
[returns termr | 
[signals signallist]; 


where arglist is a list of one or more assignments, separated by commas 
and visibility is one of: 


inheritable 
private 
public 
shared 


and modifier is one of: 


abstract 
constant 
final 
native 
static 


and signallist is a list of one or more terms, separated by commas. 


The method instruction is used to introduce a method within a class, as described in 
Program structure (see page {131]), and define its attributes. The method must be given a 
name, which must be a non-numeric symbol. This is its short name. 


If the short name of a method matches the short name of the class in which it appears, it 
is a constructor method. Constructor methods are used for constructing values (objects), 
and are described in detail in Methods and Constructors (see page B7). 


The body of the method consists of all clauses following the method instruction (if any) 
until the next method or class instruction, or the end of the program. 


The visibility, modifier, and protect keywords, and the returns and signals phrases, 
may appear in any order. 
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25.1 Arguments 


The arglist on a method instruction, immediately following the method name, is optional 
and defines a list of the arguments for the method. An argument is a value that was 
provided by the caller when the method was invoked. 


If there are no arguments, this may optionally be indicated by an “empty” pair of paren- 
theses. 


In the arglist, each argument has the syntax of an assignment (see page 57) , where the 
*=” and the following expression may be omitted. The name in the assignment provides 
the name for the argument (which must not be the same as the name of any property in 
the class). Each argument is also optionally assigned a type, or type and default value, fol- 
lowing the usual rules of assignment. If there is no assignment, the argument is assigned 
the NetRExx string type, REXx. 


» 9 b> PD) 


If there is no assignment (that is, there is no "=”) or the expression to the right of the 
returns just a type, the argument is required (that is, it must always be specified by the 
caller when the method is invoked). 


If an explicit value is given by the expression then the argument is optional; when the 
caller does not provide an argument in that position, then the expression is evaluated 
when the method is invoked and the result is provided to the method as the argument. 


Optional arguments may be omitted "from the right” only. That is, arguments may not 
be omitted to the left of arguments that are not omitted. Examples: 


method fred 

method fred() 

method fred(width, height) 

method fred(width=int, height=int 10) 


In these examples, the first two method instructions are equivalent, and take no argu- 
ments. The third example takes two arguments, which are both strings of type RExx. 
The final example takes two arguments, both of type int; the second argument is op- 
tional, and if not supplied will default to the value 10 (note that any valid expression 
could be used for the default value). 


25.2 Visibility 


Methods may be public, inheritable, private, or shared: 


¢ A public method is visible to (that is, may be used by) all other classes to which the 
current class is visible. 


An inheritable method is visible to (that is, may be used by) all classes in the same 
package and also those classes that extend (that is, are subclasses of) the current 
class. 


- A private method is visible only within the current class. 
¢ A shared method is visible within the current package but is not visible outside the 
package. Shared methods cannot be inherited by classes outside the package. 


94 


By default (i.e., if no visibility keyword is specified), methods are public. 


25.3 Modifier 


Most methods consist of instructions that follow the method instruction and implement 
the method; the method is associated with an object constructed by the class. These are 
called standard methods. The modifier keywords define that the method is not a stan- 
dard method - it is special in some way. Only one of the following modifier keywords is 
allowed: 


abstract An abstract method has the name of the method and the types (but not values) 
of its arguments defined, but no instructions to implement the method are provided 
(or permitted). 
If a class contains any abstract methods, an object cannot be constructed from it, 
and so the class itself must be abstract; the abstract keyword must be present on 
the class instruction (see page 69) . 
Within an interface class, the abstract keyword is optional on the methods of the 
class, as all methods must be abstract. No other modifier is allowed on the methods 
of an interface class. 

constant A constant method is a static method that cannot be overridden by a method 
in a subclass of the current class. That is, it is both final and static (see below). 

final A final method is considered to be complete; it cannot be overridden by a subclass 
of the current class. private methods are implicitly final. 

native A native method is a method that is implemented by the environment, not by 
instructions in the current class. Such methods have no NetRExx instructions to 
implement the method (and none are permitted), and they cannot be overridden 
by a method in a subclass of the current class. 
Native methods are used for accessing primitive operations provided by the under- 
lying operating system or by implementation-dependent packages. 

static A static method is a method that is not a constructor and is associated with the 
class, rather than with an object constructed by the class. It cannot use properties 
directly, except those that are also static (or constant). 
Static methods may be invoked in the following ways: 

1. Within the initialization expression of a static or constant property (such 
methods are invoked when the class is first loaded). 

2. By qualifying the name of the method with the name of its class (qualified 
by the package name if necessary), for example, using "Math.Sin(1.3)” or 
*java.lang.Math.Sin(1.3)”. Methods called in this way are in effect functions. 

3. By implicitly qualifying the name by including the name of its class in the uses 
phrase in the class instruction for the current class. Static methods in classes 
listed in this way can be used directly, without qualification, for example, as 
”Sin(1.3)”. They may be still be qualified, if preferred. 

In the reference implementation, stand-alone applications are started by the java 
command invoking a static method called main which takes a single argument (of 





51 This modifier may allow compilers to improve the performance of methods that are final, but may also reduce the reusability 
of the class. 
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type java.lang.String[]) and returns no result. 


25.4 Protect 


The keyword protect indicates that the method protects the current object (or class, 
for a static method) while the instructions in the method are executed. That is, the in- 
structions in the method have exclusive access to the object; if some other method (or 
construct) is executing in parallel with the invocation of the method and is protecting 
the same object then the method will not start execution until the object is no longer 
protected. 


Note that if a method or construct protecting an object invokes a method (or starts a 
new construct) that protects the same object then execution continues normally. The 
inner method or construct is not prevented from executing, because it is not executing 
in parallel. 


25.5 Binary 


The keyword binary indicates that the method is a binary method. 


In binary methods, literal strings and numeric symbols are assigned native string or 
binary (primitive) types, rather than NetRExx types, and native binary operations are 
used to implement operators where possible. When binary is not in effect (the default), 
terms in expressions are converted to NetRExx types before use by operators. The section 
Binary values and operations (see page operations:ea. describes the implications of 
binary methods and classes in detail. Notes: 


1. Only the instructions inside the body of the method are affected by the binary 
keyword; any arguments and expressions on the method instruction itself are not 
affected (this ensures that a single rule applies to all the method signatures in a 
class). 


2. All methods in a binary class are binary methods; the binary keyword on methods 
is provided for classes in which only the occasional method needs to be binary 
(perhaps for performance reasons). It is not an error to specify binary ona method 
in a binary class. 


25.6 Deprecated 


The keyword deprecated indicates that the method is deprecated, which implies that a 
better alternative is available and documented. A compiler can use this information to 
warn of out-of-date or other use that is not recommended. 


Note that individual methods in interface classes cannot be deprecated; the whole class 
should be deprecated in this case. 


96 


25.7 Returns 


The returns keyword is followed by a term, termr, that must evaluate to a type. This type 
is used to define the type of values returned by return instructions within the method. 


The returns phrase is only required if the method is to return values of a type that is not 
NetReExx strings (class RExx). If returns is specified, all return instructions (see page 
115) within the method must specify an expression. Example: 


method filer(path, name) returns File 
return File(path| |name) 


This method always returns a value which is a File object. 


25.8 Signals 


The signals keyword introduces a list of terms that evaluate to types that are Exceptions 
(see page . This list enumerates and documents the exceptions that are signalled 
within the method (or by a method which is called from the current method) but are 
not caught by a catch clause in a control construct. Example: 


method soup(cat) signals IOException, DivideByZero 


It is considered good programming practice to use this list to document unusual” ex- 
ceptions signalled by a method. Implementations that support the concept of checked 
exceptions(see page must report as an error any checked exception that is incor- 
rectly included in the list (that is, if the exception is never signalled or would always be 
caught). Such implementations may also offer an option that enforces the listing of all 
or some checked exceptions. 


25.9 Duplicate methods 


Methods may not duplicate properties or other methods in the same class. Specifically: 


¢ The short name of a method must not be the same as the name of any property in 
the same class. 

¢ The number (zero or more) and types of the arguments of a method (or any subset 
permitted by omitting optional arguments) must not be the same as those of any 
other method of the same name in the class (also checking any subset permitted by 
omitting optional arguments). 


Note that the second rule does allow multiple methods with the same name in a class, 
provided that the number of arguments differ or at least one argument differs in type. 
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Nop instruction 


nop ; 


nop is a dummy instruction that has no effect. It can be useful as an explicit “do nothing” 
instruction following a then or else clause. Example: 


select 
when a=b then nop -- Do nothing 
when a>b then say ’A > B’ 
otherwise say ’A < B’ 
end 


Note: Putting an extra semicolon instead of the nop would merely insert a null clause, 
which would just be ignored by NetRexx. The second when clause would then immedi- 
ately follow the then, and hence would be reported as an error. nop is a true instruction, 
however, and is therefore a valid target for the then clause. 
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Numeric instruction 


numeric digits [exprd]; 


form [scientific]; 
[engineering] ; 


The numeric instruction is used to change the way in which arithmetic operations are 
carried out by a program. The effects of this instruction are described in detail in the 
section on Numbers and Arithmetic (see page |155}) . 


numeric digits controls the precision under which arithmetic operations will be evalu- 


ated (see page ; 

If no expression exprd is given then the default value of 9 is used. Otherwise the 
result of the expression is rounded, if necessary, according to the current setting of 
numeric digits before it is used. The value used must be a positive whole number. 
There is normally no limit to the value for numeric digits (except the constraints 
imposed by the amount of storage and other resources available) but note that high 
precisions are likely to be expensive in processing time. It is recommended that the 
default value be used wherever possible. 

Note that small values of numeric digits (for example, values less than 6) are gen- 
erally only useful for very specialized applications. The setting of numeric digits 
affects all computations, so even the operation of loops may be affected by round- 
ing if small values are used. 

If an implementation does not support a requested value for numeric digits then 
the instruction will fail with an exception (which may, as usual, be caught with the 
catch clause of a control construct). 

The current setting of numeric digits may be retrieved with the digits special 


word (see page : 


numeric form controls which form of exponential notation (see page [162) is to be used 


for the results of operations. This may be either scientific (in which case only one, 
non-zero, digit will appear before the decimal point), or engineering (in which case 
the power of ten will always be a multiple of three, and the part before the decimal 
point will be in the range 1 through 999). The default notation is scientific. The form 
is set directly by the sub-keywords scientific or engineering; if neither sub- 
keyword is given, scientific is assumed. The current setting of numeric form 
may be retrieved with the form special word (see page ; 

If an implementation does not support a requested value for numeric form then 
the instruction will fail with an exception (which may, as usual, be caught with the 
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catch clause of a control construct). 


The numeric instruction may be used where needed as a dynamically executed instruc- 
tion in a method. 


It may also appear, more than once if necessary, before the first method in a class, in 
which case it forms the default setting for the initialization of subsequent properties in 
the class and for all methods in the class. In this case, any exception due to the numeric 
instruction is raised when the class is first loaded. 


Further, one or more numeric instructions may be placed before the first class instruc- 
tion in a program; they do not imply the start of a class. The numeric settings then apply 
to all classes in the program (except interface classes), as though the numeric instruc- 
tions were placed immediately following the class instruction in each class (except that 
they will not be traced). 
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Options instruction 


options wordlist; 


where wordlist is one or more symbols separated by blanks. 


The options instruction is used to pass special requests to the language processor (for 
example, an interpreter or compiler). 


Individual words, known as option words, in the wordlist which are meaningful to the 
language processor will be obeyed (these might control optimizations, enforce standards, 
enable implementation-dependent features, etc.); those which are not recognized will be 
ignored (they are assumed to be instructions to a different language processor). Option 
words in the list that are known will be recognized independently of case. 


There may be zero or more options instructions in a program. They apply to the whole 
program, and must come before the first class instruction (or any instruction that starts 
a class). 


In the reference implementation, the known option words are: 


binary All classes in this program will be binary (see page|7I)) classes:ea.. In binary classes, 
literals are assigned binary (primitive) or native string types, rather than NetRExx 
types, and native binary operations are used to implement operators where appropri- 
ate, as described in Binary values and operations” (see page . In classes that 
are not binary, terms in expressions are converted to the NetREXxx string type, REXX, 
before use by operators. 


comments Comments from the NetRExx source program will be passed through to the the 
Java output file (which may be saved with a .java.keep extension by using the -keep 
command option). 
Line comments become Java line comments (introduced by ”//”). Block comments be- 
come Java block comments (delimited by ”/*” and ”*/”), with nested block comments 
having their delimiters changed to *(-” and ”-)”). 

classpath The -classpath operand allows dynamic specification of the classpath used by 
the NetRexxC compiler without having to depend on the CLASSPATH environment 
variable. There is no -noclasspath counterpart. 

compact Requests that warnings and error messages be displayed in compact form. This 
format is more easily parsed than the default format, and is intended for use by editing 
environments. 
Each error message is presented as a single line, prefixed with the error token iden- 
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3.04 


3.04 


tification enclosed in square brackets. The error token identification comprises three 
words, with one blank separating the words. The words are: the source file specifica- 
tion, the line number of the error token, the column in which it starts, and its length. 
For example (all on one line): 


[D: 

test 

test.nrx 3 8 5] Error: The external name 

>class’ is a Java reserved word, so would not be 
usable from Java programs 


Any blanks in the file specification are replaced by a null (’ 
0’) character. Additional words could be added to the error token identification later. 


console Requests that compiler messages be written to console (the default). Use -noconsole 
to prevent messages being written to the console. 
This option only has an effect as a compiler option, and applies to all programs being 
compiled. 


crossref Requests that cross-reference listings of variables be prepared, by class. 


decimal Decimal arithmetic may be used in the program. If nodecimal is specified, the 
language processor will report operations that use (or, like normal string comparison, 
might use) decimal arithmetic as an error. This option is intended for performance- 
critical programs where the overhead of inadvertent use of decimal arithmetic is un- 
acceptable. 


diag Requests that diagnostic information (for experimental use only) be displayed. The 
diag option word may also have side-effects. 


ecj Indicates to the translator a preference for using the ecj compiler, if available 


explicit Requires that all local variables must be explicitly declared (by assigning them 
a type but no value) before assigning any value to them. This option is intended to 
permit the enforcement of “house styles” (but note that the NetRExx compiler always 
checks for variables which are referenced before their first assignment, and warns of 
variables which are set but not used). 


format Requests that the translator output file (Java source code) be formatted for im- 
proved readability. Note that if this option is in effect, line numbers from the input 
file will not be preserved (so run-time errors and exception trace-backs may show 
incorrect line numbers). 


java Requests that Java source code be produced by the translator. If nojava is specified, no 
Java source code will be produced; this can be used to save a little time when checking 
of a program is required without any compilation or Java code resulting. 

javac Indicates to the translator a preference for using the javac compiler, if available 

keepasjava Requests that Java source code is kept as [programfile].java. Implies -replace. 
This option only has an effect as a compiler option, and applies to all programs being 
compiled. 


logo Requests that the language processor display an introductory logotype sequence 
(name and version of the compiler or interpreter, etc.). 


replace Requests that replacement of the translator output (.java) file be allowed. The de- 
fault, noreplace, prevents an existing .java file being accidentally overwritten. 
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savelog Requests that compiler messages be written to the file NetRExxC.log in the cur- 
rent directory. The messages are also displayed on the console, unless -noconsole is 
specified. 
This option only has an effect as a compiler option, and applies to all programs being 
compiled. 


sourcedir Requests that all .class files be placed in the same directory as the source file from 
which they are compiled. Other output files are already placed in that directory. Note 
that using this option will prevent the -run command option from working unless the 
source directory is the current directory. 


strictargs Requires that method invocations always specify parentheses, even when no ar- 
guments are supplied. Also, if strictargs is in effect, method arguments are checked 
for usage - a warning is given if no reference to the argument is made in the method. 


strictassign Requires that only exact type matches be allowed in assignments (this is 
stronger than Java requirements). This also applies to the matching of arguments in 
method calls. 


strictcase Requires that local and external name comparisons for variables, properties, 
methods, classes, and special words match in case (that is, names must be identical to 
match). 


strictimport Requires that all imported packages and classes be imported explicitly using 
import instructions. That is, if in effect, there will be no automatic imports (see page 
79) , except those related to the package instruction. 
This option only has an effect as a compiler option, and applies to all programs being 
compiled. 


strictprops Requires that all properties, including those local to the current class, be qual- 
ified in references. That is, if in effect, local properties cannot appear as simple names 
but must be qualified by this. (or equivalent) or the class name (for static properties). 


strictsignal Requires that all checked exceptions (see page signalled within a method 
but not caught by a catch clause be listed in the signals phrase of the method in- 
struction. 


symbols Symbol table information (names of local variables, etc.) will be included in any 
generated .class file. This option is provided to aid the production of classes that are 
easy to analyse with tools that can understand the symbol table information. The use 
of this option increases the size of .class files. 


trace, traceX If given as trace, trace1, or trace2, then trace instructions are accepted. 
‘The trace output is directed according to the option word: trace1 requests that trace 
output is written to the standard output stream, trace or trace2 imply that the out- 
put should be written to the standard error stream (the default). 
If notrace is given, then trace instructions are ignored. The latter can be useful to 
prevent tracing overheads while leaving trace instructions in a program. 

utf8 If given, clauses following the options instruction are expected to be encoded using 
UTF-8, so all Unicode characters may be used in the source of the program. 
In UTF-8 encoding, Unicode characters less than ’\u0080’ are represented using 
one byte (whose most-significant bit is 0), characters in the range ’\u0080’ through 
’\u07FF are encoded as two bytes, in the sequence of bits: 


110xxxxx 10xXxXxXxXxx 
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where the eleven digits shown as x are the least significant eleven bits of the character, 
and characters in the range ’\u0800’ through ’\uF FFF’ are encoded as three bytes, in 
the sequence of bits: 


1110xxxx 10xxxxxx 10xxxxxx 
where the sixteen digits shown as x are the sixteen bits of the character. 
Tf nout 8 is given, following clauses are assumed to comprise only Unicode characters 


in the range ’\x00’ through ?\xFF’, with the more significant byte of the encoding of 
each character being 0. 


Note: this option only has an effect as a compiler option, and applies to all programs 
being compiled. If present on an options instruction, it is checked and must match 
the compiler option (this allows processing with or without ut f8 to be enforced). 


verbose, verboseX Sets the “noisiness” of the language processor. The digit X may be any 
of the digits 0 through 5; if omitted, a value of 3 is used. The options noverbose and 
verboseo both suppress all messages except errors and warnings. 

warnexit0 Exit the translator with returncode 0 even if warnings are issued. This option 
only has an effect as a compiler option, and applies to all programs being compiled. 


Prefixing any of the above with “no” turns the selected option off. Example: 
options binary nocrossref nostrictassign strictargs 
‘The default settings of the various options are: 


nobinary nocomments nocompact console crossref decimal nodiag noexplicit 
noformat java logo noreplace nosavelog nosourcedir nostrictargs 
nostrictassign nostrictcase nostrictimport nostrictprops nostrictsignal 
nosymbols trace2 noutf8& verbose3 


When an option word is repeated (in the same options instruction or not), or conflicting 
option words are specified, then the last use determines the state of the option. 

All option words may also be set as command line options when invoking the processor, by 
prefixing them with ”-”: Example: 

java COM.ibm.netrexx.process.NetRexxC -format foo.nrx 


In this case, any options may come before, after, or between file specifications. 


With the except of the ut f8 option (see above), options set with the options instruction 
override command-line settings, following the “last use” rule. 


For more information, see the installation and user documentation for your implementa- 
tion. 
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Package instruction 


package name; 


where name is one or more non-numeric symbols separated by periods. 


The package instruction is used to define the package to which the class or classes in the 
current program belong. Classes that belong to the same package have privileged access 
to other classes in the same package, in that each class is visible to all other classes in the 
same package, even if not declared public. Packages also conveniently group classes for 
use by the import instruction (see page [79) . 


The name must specify a package name, which is one or more non-numeric symbols, 
separated by periods, with no blanks. 


There must be at most one package instruction in a program. It must precede any class 
instruction (or any instruction that would start the default class). 


If a program contains no package instruction then its package is implementation- 
defined. Typically it is grouped with other programs in some implementation-defined 
logical collection, such as a directory in a file system. Examples: 


package testpackage 
package com.ibm.venta 


When a class is identified as belonging to a package, it has a qualified class name, which 
is its short name, as given on the class instruction (see page 69) , prefixed with the 
package name and a period. For example, if the short name of a class is >RxLanguage” 
and the package name is ”com.ibm.venta” then the qualified name of the class would be 
*com.ibm.venta.RxLanguage’. 


In the reference implementation, packages are kept in a hierarchy derived from the Java 
classpath, where the segments of a package name correspond to a path in the hierarchy. 
‘The hierarchy is typically the directories in a file system, or some equivalent (such as a 
*Zip’ archive file), and so package names should be considered case-sensitive (as some Java 
implementations use case-sensitive file systems). 
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Parse instruction 


parse term template; 


where template is one or more non-numeric symbols 
separated by blanks and/or patterns, and a pattern is one of: 


literalstring 
[indicator] number 
[indicator] (symbol) 


and indicator is one of +, -, or =. 


The parse instruction is used to assign characters (from a string) to one or more variables 
according to the rules and templates described in the section Parsing templates (see page 


147). 


The value of the term is expected to be a string; if it is not a string, it will be converted to 
a string. 


Any variables used in the template are named by non-numeric symbols (that is, they 
cannot be an array reference or other term); they refer to a variable or property in the 
current class. Any values that are used in patterns during the parse are converted to 
strings before use. 


Any variables set by the parse instruction must have a known string type, or are given 
the NetRExx string type, REXx, if they are new. 


The term itself is not changed unless it is a variable which also appears in the template 
and whose value is changed by being in the template. 


Example: 
parse wordlist wordl wordlist 


In this idiomatic example, the first word is removed from wordlist and is assigned to the 
variable word1, and the remainder is assigned back to wordlist. 


Notes: 


1. The special words ask, source, and version, as described in the section Special 
names and methods(see page |139), allow: 


parse ask x -- parses a line from input stream 
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parse source x -- parses ’Java method filename’ 
parse version x -- parses ’NetRexx verston date’ 


These special words may also be used within expressions. 

2. Similarly, it is recommended that the initial (main) method in a stand-alone appli- 
cation place the command string passed to it in a variable called arg. 2 
If this is done, the instruction: 


parse arg template 


will work, in a stand-alone application, in the same way as in Rexx (even though 
arg is not a keyword in this case). 3 





52 In the reference implementation, this is automatic if the main method is generated by the NetRexx language processor. 
53 Note, though, that the command string may have been edited by the environment; certain characters may not be allowed, 
multiple blanks may have been reduced to single blanks, etc. 
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Properties instruction 


properties [visibility] [modifier] [deprecated] [unused]; 
where visibility is one of: 


inheritable 
private 
public 
shared 


and modifier is one of: 


constant 
static 
transient 
volatile 


and there must be at least one visibility or modifier keyword. 


The properties instruction is used to define the attributes of following property vari- 
ables, and therefore must precede the first method instruction in a class. A properties 
instruction replaces any previous properties instruction (that is, the attributes speci- 
fied on properties instructions are not cumulative). 


The visibility, modifier, deprecated, and unused keywords may be in any order. 


Note: An unqualified properties statement (one that has no visibility or modifier key- 
word), is not in error, but generates a variable properties, which is most probably not 
the intention of the programmer. The reference implementation issues a warning but al- 
lows this practice. 


An example of the use of properties instructions may be found in the Program Struc- 
ture section (see page |131)) . 
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31.1 Visibility 


Properties may be public, inheritable, private, or shared: 54 


* A public property is visible to (that is, may be used by) all other classes to which the 
current class is visible. 

¢ An inheritable property is visible to (that is, may be used by) all classes in the same 
package and also those classes that extend (that is, are subclasses of) the current 
class, and which qualify the property using an object of the subclass, or either this 
or super. 

+ A private property is visible only within the current class. 


* A shared property is visible within the current package but is not visible outside the 
package. Shared properties cannot be inherited by classes outside the package. 


By default, if no properties instruction is used, or visibility is not specified, properties 
are inheritable (but not public). EB 


31.2 Modifier 


Properties may also be constant, static, transient, or volatile: 


« A constant property is associated with the class, rather than with an instance of the 
class (an object). It is initialized when the class is loaded and may not be changed 
thereafter. 

* A static property is associated with the class, rather than with an instance of the class 
(an object). It is initialized when the class is loaded, and may be changed thereafter. 

« A transient property is a property which should not be saved when an instance of 
the class is saved (made persistent). 

- A volatile property may change asynchronously, outside the control of the class, 
even when no method in the class is being executed. If an implementation does 
not allow asynchronous modification of properties, it should ignore this keyword. 


Constant and static properties exist from when the class is first loaded (used), even if 
no object is constructed by the class, and there will only be one copy of each property. 
Other properties are constructed and initialized only when an object is constructed by 
the class; each object then has its own copy of such properties. 


By default, if no properties instruction is used, or modifier is not specified, properties 
are associated with an object constructed by the class. 


31.3 Deprecated 


The keyword deprecated indicates that any property introduced by this instruction is 
deprecated, which implies that a better alternative is available and documented. A com- 





54 An experimental option for visibility, indirect, is described in Appendix B (see page 143) . 
55 The default, here, was chosen to encourage the “encapsulation” of data within classes. 
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piler can use this information to warn of out-of-date or other use that is not recom- 
mended. 


31.4 Unused 


The keyword unused indicates that the private properties which follow are not referenced 
explicitly in the code for the class, and so a language processor should not warn that they 
exist but have not been used. Ifa visibility keyword is specified it must be private. 


For example: 


properties private constant unused 
-- Serialization version 
serialVersionUID=long 8245355804974198832 


31.5 Properties in interface classes 


In interface classes (see page 7 1]) , properties must be both public and constant. In such 
classes, these attributes for properties are the default and the properties instruction 
must not be used. 
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Return instruction 


return [expression]; 


return is used to return control (and possibly a result) from a NetRExx program or 
method to the point of its invocation. 


‘The expression (if any) is evaluated, active control constructs are terminated (as though 
by a leave instruction), and the value of the expression is passed back to the caller. 


The result passed back to the caller is a string of type RExx, unless a different type was 
specified using the returns keyword on the method instruction (see page for the 
current method. In this case, the type of the value of the expression must match (or be 
convertible to, as by the rules for assignment) the type specified by the returns phrase. 


Within a method, the use of expressions on return must be consistent. That is, either 
all return instructions must specify a expression, or none may. If a returns phrase is 
given on the method instruction for the current method then all return instructions 
must specify an expression. 
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Say instruction 


say [expression]; 


say writes a string to the default output character stream. This typically causes it to be 
displayed (or spoken, or typed, etc.) to the user. 


Example: 


data=100 
say data ’divided by 4 =>’ data/4 
/* would display: ”100 divided by 4 => 25” x/ 


The result of evaluating the expression is expected to be a string; if it is not a string, 
it will be converted to a string. This result string is written from the program via an 
implementation-defined output stream. 


By default, the result string is treated as a “line” (an implementation-dependent mech- 
anism for indicating line termination is effected after the string is written). If, however, 
the string ends in the NUL character (’\-’ or ’\0’) then that character is removed and line 
termination is not indicated. 


The result string may be of any length. If no expression is specified, or the expression 
result is null, then an empty line is written (that is, as though the expression resulted in 
a null string). 
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Select instruction 


select [label name] [protect term] [case expression]; 

whenlist 
[otherwise[;] instructionlist] 

[catch [vare =] exception; 
instructtionlist]... 

[finally[; ] 
instructtonlist] 

end [name]; 


where name is a non-numeric symbol 
and whenlist is one or more whenconstructs 
and whenconstruct is: 
when expresston[, expression]... [;] then[;] tnstruction 


and instructionlist is zero or more instructions. 


select is used to conditionally execute one of several alternatives. The construct may 
optionally be given a label, and may protect an object while the instructions in the con- 
struct are executed; exceptional conditions can be handled with catch and finally, 
which follow the body of the construct. 


Starting with the first when clause, each expression in the clause is evaluated in turn from 
left to right, and if the result of any evaluation is 1 (or equals the case expression, see 
below) then the test has succeeded and the instruction following the associated then 
(which may be a complex instruction such as if, do, loop, or select) is executed and 
control will then pass directly to the end. 


If the result of all the expressions in a when clause is 0, control will pass to the next when 
clause. 


Note that once an expression evaluation in a when clause has resulted in a successful test, 
no further expressions in the clause are evaluated. 


If none of the when expressions result in 1, then control will pass to the instruction list (if 
any) following otherwise. In this situation, the absence of an otherwise is a run-time 
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error. £4 Notes: 


1. An instruction may be any assignment, method call, or keyword instruction, in- 
cluding any of the more complex constructions such as do, Loop, if, and the select 
instruction itself. A null clause is not an instruction, however, so putting an extra 
semicolon after the then is not equivalent to putting a dummy instruction (as it 
would be in C or PL/I). The nop instruction is provided for this purpose. 


2. The keyword then is treated specially, in that it need not start a clause. This allows 
the expression on the when clause to be terminated by the then, without a ”;” being 
required - were this not so, people used to other computer languages would be 
inconvenienced. Hence the symbol then cannot be used as a variable name within 


the expression. 


34.1 Label phrase 


If Label is used to specify a name for the select group, then a leave instruction (see page 
which specifies that name may be used to leave the group, and the end that ends the 
group may optionally specify the name of the group for additional checking. Example: 


select label roman 
when a=b then say ’same’ 
when a<b then say ’1lo’ 
otherwise 
say ’hi’ 
if a=0 then leave roman 
say ’a non-0’ 
end roman 


In this example, if the variable a has the value 0 and b is negative then just "hi is dis- 
played. 


34.2 Protect phrase 


If protect is given it must be followed by a term that evaluates to a value that is not 
just a type and is not of a primitive type; while the select construct is being executed, 
the value (object) is protected - that is, all the instructions in the select construct have 
exclusive access to the object. 


Both label and protect may be specified, in any order, if required. 





56 In the reference implementation, a NoOtherwiseException is raised. 

57 Strictly speaking, then should only be recognized if not the name of a variable. In this special case, however, NetRExx language 
processors are permitted to treat then as reserved in the context of a when clause, to provide better performance and more useful 
error reporting. 
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34.3. Case phrase 


If case is given it must follow any label or protect phrase, and must be followed by an 
expression. 


When case is used, the expression following it is evaluated at the start of the select con- 
struct. The result of the expression is then compared, using the strict equality operator 
(==), to the result of evaluating the expression or expressions in each of the when clauses 
in turn until a match is found. As usual, if no match is found then control will pass to 
the instruction list (if any) following otherwise, and in this situation the absence of an 
otherwise is a run-time error. For example, in: 


select case i+1 

when 1 then say ’one’ 

when 1+1 then say ’ two’ 

when 3, 4, 5 then say ’many’ 
end 


then if i had the value 1 then the message displayed would be ” two”. 


The third when clause in the example demonstrates the use of the multiple expressions in 
a when clause in this context. Similar to a select without case, each expression is evalu- 
ated in turn from left to right and is then compared to the result of the case expression. 
As soon as one matches that result, execution of the when clause stops (any further ex- 
pressions are not evaluated) and the instruction following the associated then clause is 
executed. 


Notes: 


1. When case is used, the result of evaluating the expression following each when no 
longer has to be 0 or 1. Instead, it must be possible to compare each result to the 
result of the case expression. 


2. The case expression is evaluated only on entry to the select construct; it is not 
re-evaluated for each when clause. 


3. An exception raised during evaluation of the case expression will be caught by a 
suitable catch clause in the construct, if one is present. Similarly, evaluation of the 
case expression is protected by the protect phrase, if one is present. 


4. In the reference implementation, a select case construct will be translated into a 
Java switch construct provided that it meets the following criteria: 
« The type of the case expression is byte, char, int, or short. 
¢ The value of all the expressions on the when clauses are primitive constants (that 
is, they consist of only constants of primitive types and operators valid for them 
and so may be evaluated at compile time). 
« No two expressions on the when clauses evaluate to the same value. 
¢ It is not subject to tracing. 
Under these conditions the semantics of the switch construct match those defined for 
select. The example shown above would be translated to a switch construct if i had 
type int and options binary were in effect. 


121 


34.4 Exceptions in select constructs 


Exceptions that are raised by the instructions within the body of the group, or during 
evaluation of the case expression, may be caught using one or more catch clauses that 
name the exception that they will catch. When an exception is caught, the exception 
object that holds the details of the exception may optionally be assigned to a variable, 
vare. 


Similarly, a finally clause may be used to introduce instructions that will always be 
executed at the end of the select group, even if an exception is raised (whether caught or 
not). 


The Exceptions section (see page has details and examples of catch and finally. 
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Signal instruction 


signal term; 


The signal instruction causes an “abnormal” change in the flow of control, by raising 
an exception. 


The exception term may bea term that constructs or evaluates to an exception object, or it 
may be expressed as the name of an exception type (in which case the default constructor, 
with no arguments, for that type is used to construct an exception object). The exception 
object then represents the exception and is available, if required, when the exception is 
handled. 


The handling of exceptions is detailed in the Exceptions section (see page |169). In sum- 
mary, when an exception is signalled, all active pending do groups, Loop loops, if con- 
structs, and select constructs may be ended. For each one in turn, from the innermost: 


1. No further clauses within the body of the construct will be executed (in this respect, 
signal acts like a leave for the construct). 

2. The instructionlist following the first catch clause that matches the exception, if 
any, is executed. 

3. The instructionlist following the finally clause for the construct, if any, is executed. 


If a catch matched the exception the exception is deemed handled, and execution re- 
sumes as though the construct ended normally (unless a new exception was signalled 
in the catch or finally instruction lists, in which case it is processed). Otherwise, any 
enclosing construct is ended in the same manner. If there is no enclosing construct, then 
the current method is ended and the exception is signalled in the caller. 


Examples: 


signal RxErrorTrace 
signal DivideException(’Divide by zero’) 


In the reference implementation, the term must either 


¢ evaluate to an object that is assignable to the type Throwable (for example, a subclass 
of Exception or RuntimeException). 

* bea type that is a subclass of Throwable, in which case the default constructor (with 
no arguments) for the given type is used to construct the exception object. 
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Trace instruction 


trace traceoption; 


where traceoption is one of: 
tracesetting 
var [varlist] 


where tracesetting is one of: 


all 
methods 
off 
results 


and varlist is one or more variable names, optionally prefixed with a + or - 


The trace instruction is used to control the tracing of the execution of NetRExx meth- 
ods, and is primarily used for debugging. It may change either the general trace setting 
or may select or deselect the tracing of individual variables. 


Within methods, the trace instruction changes the trace setting or variables tracing 
when it is executed, and affects the tracing of all clauses in the method which are then 
executed (until changed by a later trace instruction). 


One or more trace instructions may appear before the first method in a class, one of 
which may set the initial trace setting for all methods in the class (the default is of f) 
and others may set up variables tracing that applies to all the methods in the class. These 
act as though the trace instructions were placed immediately following the method in- 
struction in each method (except that they will not be traced). 


Similarly, one or more trace instructions may be placed before the first class instruc- 
tion in a program; they do not imply the start of a class. One of these may set the initial 
trace setting and others may set up variables tracing for all classes in the program (ex- 
cept interface classes) and act as though the trace instructions were placed immediately 
following the class instruction in each class. 
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36.1 Tracing clauses 


The trace setting controls the tracing of clauses in a program, and may be one of the 
following: 


all All clauses (except null clauses without commentary) which are in methods and 
which are executed after the trace instruction will be traced. If trace allis placed 
before the first method in the current class, the method instructions in the class, to- 
gether with the values of the arguments passed to each method, will be traced when 
the method is invoked (that is, trace all implies trace methods). 


methods All method clauses in the class will be traced when the method they introduce 
is invoked, together with the values of the arguments passed to each method; no 
other clauses, or results, will be traced. The trace methods instruction must be 
placed before the first method in the current class (as otherwise it would have no 
effect). 


off Turns tracing off; no following clauses, variables, or results will be traced. 


results All clauses (except null clauses without commentary) which are in methods and 
which are executed after the trace instruction will be traced, as though trace all 
had been requested. In addition, the results of all expression evaluations and any 
results assigned to a variable by an assignment, Loop, or parse instruction are also 
traced. 
If trace results is placed before the first method in the current class, the method 
instructions in the class will be traced when the method is invoked, together with 
the values of the arguments passed to each method. 


Notes: 


1. Tracing of clauses shows the data from the source of the program, starting at the 
first character of the first token of the clause and including any commentary from 
that point until the end of the clause. 


2. When a loop is being traced, the loop clause itself will be traced on every iteration 
of the loop, as indicated by the programmer’s model (see page 0) ; the end clause 
is only traced once, when the loop completes normally. 


3. With trace results, an expression is not traced if it is immediately used for an 
assignment (in an assignment instruction, or when the control variable is initialized 
in a loop instruction). The assignment will trace the result of the expression. 


36.2 Tracing variables 


The var option adds names to a list of monitored variables; it can also remove names 
from the list. If the name of a variable in the current class or method is in the list, then 
trace results is turned on for any assignment, loop, or parse clause that assigns a 
new value to the named variable. 


Variable names are specified by listing them after the var keyword. Each name may be 
optionally prefixed by a + or a - sign. A + sign indicates that the variable is to be added 
to the list of monitored variables (the default), and a - sign indicates that the variable is 
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to be removed from the list. Blanks may be added before and after variable names and 
signs to separate the tokens and to improve readability. For example: 


trace var abc 

-- now variables a, b, and c will be traced 
trace var -b -c d 

-- now variables a and d will be traced 


Notes: 


1. Names in the list following the var keyword are simple symbols that name variables 
in the current class or current method. The variables may be properties, method 
arguments, or local variables, and may be of any type, including arrays. The names 
are not case-sensitive; any variables whose names match, independent of case, will 
be monitored. 


2. No variable name can appear more than once in the list on one trace var instruc- 
tion. However, it is not an error to add the name of a variable which does not exist 
or is not then assigned a value. Similarly, it is not an error to remove a name which 
is not currently being monitored. 

3. One or more trace var instructions (along with one other trace instruction) are 
allowed before the first method in a class. They all modify an initial list of mon- 
itored variables which is then used for all methods in the class. Similarly, trace 
var instructions are allowed before the first class in a program, in which case they 
apply to all classes (except interface classes). 


4, Other trace instructions do not affect the list of monitored variables. The trace 
off instruction may be used to turn off tracing completely; in this case trace var 
(with or without any variable names) will then turn the tracing of variables back 
on, using the current (or modified) variable list. 

5. For a parse instruction, only monitored variables have their assignments traced 
(unless trace results is already in effect). 


36.3 The format of trace output 


Trace output is either clauses from the program being traced, or results (such as the 
results from expressions). 


The first clause or result traced on any line will be preceded by its line number in the 
program; this is right-justified in a space which allows for the largest line number in the 
program, plus one blank. Following clauses or results from the same line are preceded 
by white space of the same width; however, any change of line number causes the line 
number to be included. 


Clauses that are traced will be displayed with the formatting (indention) and layout used 
in the original source stream for the program, starting with the first character of the first 
token of the clause. 


Results (if requested) are converted to a string for tracing if necessary, are not indented, 
and have a double quote prefixed and suffixed so that leading and trailing blanks are ap- 
parent; if, however, the result being traced is null (see page |[140) then the string ”[null]” 
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TABLE 8: Trace identifier tags 














kak 
identifies the first line of the source of a single clause, i.e., the data actually in the program. 

xk-k 
identifies a continuation line from the source of a single clause. Continuations may be due to 
the use of a continuation character (see page 23) or to the use of a block comment (see page 20) 
which spans more than one line. 

>a> 
Identifies a value assigned to a method argument of the current method. The name of the argu- 
ment is included in the trace. 

>p> 
Identifies a value assigned to a property. The name of the property is included in the trace if the 
property is in the current class. 

>v> 


Identifies a value assigned to a local variable in the current method. The name of the variable is 
included in the trace. 





»> 
Identifies the result of an expression evaluation that is not used for an assignment (for example, 


an argument expression in a method call). 





Reserved for error messages that are not supplied by the environment underlying the imple- 
mentation. 


is shown (without quotes). For results with an associated name (the values assigned to 
local variables, method arguments, or properties in the current class), the name of the 
result precedes the data, separated by a single blank. 


For clarity, implementations may replace “control codes” in the encoding of results (for 
example, EBCDIC values less than ’\x40’, or Unicode values less than ’\x20’) by a ques- 
tion mark (”?”). All lines displayed during tracing have a three character tag to identify 
the type of data being traced. This tag follows the line number (or the space for a line 
number), and is separated from the line number by a single blank. The traced clause or 
result follows the tag, after another blank. The identifier tags are listed in table 8} 


If a trace line is produced in a different context (program or thread) from the preceding 
trace line (if any) then a trace context line is shown. This shows the name of the program 
that produced the trace line, and also the name of the thread (and thread group) of the 
context. 


The thread group name is not shown if it is main, and in this case the thread name is 
then also suppressed if its name is main. 


Examples: If the following instructions, starting on line 53 of a 120-line program, were 
executed: 


trace all 
if i=1 then say ’Hello’ 
else say ’7i<>1’ 
say - 
7A continued Line’ 


the trace output (if i were 1) would be: 
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54 x=* if i=l 

x=* then 

*=k say ’Hello’ 
56 *=*x Say - 
57 *-* ’A continued line’ 


Similarly, for the 3-line program: 


trace results 
number=1/7 
parse number before ’.’ after 


the trace output would be: 


2 *=*k number=1/7 
>v> number ”@.142857143” 

3 *=* parse number before ’.’ after 
>v> before ”0” 
>v> after ”142857143” 


Notes: 


1. Trace output is written to an implementation-defined output stream (typically the 
*standard error” output stream, which lets it be redirected to a destination separate 
from the default destination for output which is used by the say instruction). 

2. In some implementations, the use of trace instructions may substantially increase 
the size of classes and the execution time of methods affected by tracing. 

3. With some implementations it may be possible to switch tracing on externally, 
without requiring modification to the program. 





58 In the reference implementation, options notrace may be used to disable all trace instructions and hence ensure that tracing 
overhead is not accidentally incurred. 
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Program structure 


A NetRExx program is a collection of clauses (see page derived from a single 
implementation-defined source stream (such as a file). When a program is processed 
by a language processor © it defines one or more classes. Classes are usually introduced 
by the class instruction (see page 69), but if the first is a standard class, intended to be 
run as a stand-alone application, then the class instruction can be omitted. In this case, 
NetRexx defines an implied class and initialization method that will be used. 


The implied class and method permits the writing of ”low boilerplate” programs, with 
a minimum of syntax. The simplest, documented, NetRExx program that has an effect 
might therefore be: 


Example: 


Listing 37.1: hello.nrx 


1 /x This is a very simple NetRexx program ,/ 


2 Say 


"Hello World!'! 


In more detail, a NetRExx program consists of: 


1. 


ee 


An optional prolog (package, import, and options instructions). Only one package 
instruction is permitted per program. 


One or more class definitions, each introduced by a class instruction. 


A class definition comprises: 


1. 


2. 


The class instruction which introduces the class (which may be inferred, see be- 
low). 
Zero or more property variable assignments, along with optional properties in- 
structions that can alter their attributes, and optional numeric and trace instruc- 
tions. Property variable assignments take the form of an assignment (see page 57) , 
with an optional ”=” and expression, which may: 
* just name a property (by omitting the "=” and expression of the assignment), 
in which case it refers to a string of type REXx 
* assign a type to the property (when the expression evaluates to just a type) 
* assign a type and initial value to the property (when the expression returns a 
value). 


. Zero or more method definitions, each introduced by a method instruction (which 


may be inferred if the class instruction is inferred, see below). 


A method definition comprises: 





5° Such as a compiler or interpreter. 
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« Any NetRexx instructions, except the class, method, and properties instructions 
and those allowed in the prolog (the package, import, and options instructions). 


Example: 


Listing 37.2: testclass.nrx 


1 /x A program with two classes ,/ 

2 import java.applet. -- for example 

3 

4 class testclass extends Applet 

5 properties public 

6 state -- property of type 'Rexx' 

7 i=int -- property of type 'int' 

8 properties constant 

9 j=int 3 -- property initialized to '3' 


u = =method start 
2 say 'I started' 
B state='start' 


1s method stop 
16 say 'I stopped' 
7 state='stop' 


19 Class anotherclass 
2 method testing 
21 loop i=1 to 10 


2 Say ‘1, 2, 35 422% 
23 if i=7 then return 
24 end 

25 return 


27 +=method anothertest 
28 say "1, 2; 3,5. 4' 


This example shows a prolog (with just an import instruction) followed by two classes. 
The first class includes two public properties, one constant property, and two methods. 
The second class includes no properties, but also has two methods. 


Note that a return instruction implies no static scoping; the content of a method is 
ended by a method (or class) instruction, or by the end of the source stream. The return 
instruction at the end of the testing method is, therefore, unnecessary. 


37.1 Program defaults 


The following defaults are provided for NetRExx programs: 


1. If, while parsing prolog instructions, some instruction that is not valid for the pro- 
log and is not a class instruction is encountered, then a default class instruction 
(with an implementation-provided short name, typically derived from the name 
of the source stream) is inserted. If the instruction was not a method instruction, 
then a default method instruction (with a name and attributes appropriate for the 
environment, such as main) is also inserted. 

In this latter case, it is assumed that execution of the program will begin by invo- 
cation of the default method. In other words, a “stand-alone” application can be 
written without explicitly providing the class and method instructions for the first 
method to be executed. An example of such a program is given in Appendix A (see 


page [197)) . 
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In the reference implementation, the main method in a stand-alone application 
is passed the words forming the command string as an array of strings of type 
java.lang.String (one word to each element of the array). When the NetRExx ref- 
erence implementation provides the main method instruction by default, it also 
constructs a NetRExx string of type RExx from this array of words, with a blank 
added between words, and assigns the string to the variable arg. 

The command string may also have been edited by the underlying operating system 
environment; certain characters may not be allowed, multiple blanks or whitespace 
may have been reduced to single blanks, etc. 

2. If a method ends and the last instruction at the outer level of the method scope is 
not return then a return instruction is added if it could be reached. In this case, if 
a value is expected to be returned by the method (due to other return instructions 
returning values, or there being a returns keyword on the method instruction), an 
error is reported. 


Language processors may provide options to prevent, or warn of, these defaults being 
applied, as desired. 
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Minor and Dependent classes 


A minor class in NetREXx is a class whose name is qualified by the name of another class, 
called its parent, and a dependent class is a minor class that has a link to its parent class 
that allows a child object simplified access to its parent object and its properties. 


38.1 Minor classes 


A minor class in NetREXx is a class whose name is qualified by the name of another class, 
called its parent. This qualification is indicated by the form of the name of the class: the 
short name of the minor class is prefixed by the name of its parent class (separated by a 
period). For example, if the parent is called Foo then the full name of a minor class Bar 
would be written Foo. Bar. The short name, Bar, is used for the name of any constructor 
method for the class; outside the class it can only be used to identify the class in the 
context of the parent class (or from children of the minor class, see below). 


The names of minor classes may be used in exactly the same way as other class names 
(types) in programs. For example, a property might be declared and initialized thus: 
abar=Foo.Bar null -- this has type Foo.Bar 

or, if the class has a constructor, perhaps: 


abar=Foo.Bar() -- constructs a Foo.Bar object 


Minor classes must be in the same program (and hence in the same package) as their 
parent. They are introduced by a class instruction that specifies their full name, for 
example: 


class Foo.Bar extends SomeClass 


Minor classes must immediately follow their parent class. 


Minor classes may have a parent which is itself a minor class, to any depth; the name 
and the positioning rules are extended as necessary. For example, the following classes 
might exist in a program: 


class Foo 
class Foo.Bar 
class Foo.Bar.Nod 
class Foo.Bar.Pod 
class Foo.Car 





© This allows compilers that generate Java source code to preserve line numbering. 
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As before, the children of Foo. Bar immediately follow their parent. The list of children 
of Foo can be continued after the children of Foo.Bar have all been specified. 


Note that the short name (last part of the name) of a minor class may not be the same as 
the short name of any of its parents (a class Foo. Bar. Foo or a class Foo. Bar.Bar would 
be in error, for example). This allows minor classes to refer to their parent classes by their 
short name without ambiguity. 


38.1.1 Constructing objects in minor classes 


A parent class can construct an object of a child class in the usual manner, by simply 
specifying its constructor (identified by its short name, full name, or qualified name). 
For example, a method in the Foo.Bar class above could construct an object of type 
Foo.Bar.Nod using: 


anod=Nod() 


(assuming the Foo. Bar .Nod class has a constructor that takes no arguments). 


Similarly, minor classes can refer to the types and constructors of any of its parents by 
simply using their short names. Hence, the Foo.Bar.Nod class could construct objects 
of its parents’ types thus: 


abar=Bar () 
afoo=Foo() 


(again assuming the parent classes have constructors that take no arguments). 


Classes other than the parent or an immediate child must use the full name (if necessary, 
qualified by the package name) to refer to a minor class or its constructor. 


38.2 Dependent classes 


As described in the last section, minor classes provide an enhanced packaging (naming) 
mechanism for classes, allowing classes to be structured within packages. A stronger link 
between a child class and its parent is indicated by the modifier keyword dependent on 
the child class, which indicates that the child is a dependent class. For example: 


class Foo.Dep dependent extends SomeClass 
method Dep -- this is the constructor 


An object constructed from a dependent class (a dependent object) is linked to the con- 
text of an object of its parent type (its parent object). The linkage thus provided allows 
the child object simplified access to the parent object and its properties. 


In the example, an object of type Foo.Dep can only be constructed in the context of a 
parent object, which must be of type Foo. 
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38.2.1 Constructing dependent objects 


A parent class can construct a dependent object in the same way as when constructing 
objects of other child types; that is, by simply specifying its constructor. In this case, 
however, the current object (this) becomes the parent object of the newly constructed 
object. For example, a method in the Foo class above could construct a dependent object 
of type Foo. Dep using: 


adep=Dep () 


(assuming the Dep class has a constructor that takes no arguments). 


In general, for a class to construct an object from a dependent class, it must have a ref- 
erence to an object of the parent class (which will become the parent of the new object), 
and the constructor must be called (by its short name) in the context of that parent ob- 
ject. For example: 


parentObject=Foo() 
adep=parentObject.Dep() 


(In the same way, the first example could have been written: 
adep=this.Dep() 


within the parent class the this. is implied.) 


In order to subclass a dependent class, the constructor of the dependent class must be 
invoked by the subclass constructor in a similar manner. In this case, a qualified call to 
the usual special constructor super is used, for example: 


class ASub extends Foo.Dep 
method Asub(afoo=Foo) 
afoo.super() 


The qualifier (afoo in the example) must be either the name of an argument to the con- 
structor, or the special word parent (if the classes share a common parent class), or the 
short name of a parent class followed by . this (see below). The call to super must be the 
first instruction in the method, as usual, and it must be present (it will not be generated 
automatically by the compiler). 


38.2.2 Access to parent objects and their properties 


Dependent classes have simplified access to their parent objects and their properties. In 
particular: 


¢ The special word parent may be used to refer to the parent object of the current 
object. It may appear alone in a term, or at the start of a compound term. It can 
only be used in non-static contexts in a dependent class. 

* In general, any of the objects in the chain of parents of a dependent object may be 
referred to by qualifying the special word this with the short name of the parent 
class. For example, extending the previous example, if the class Foo. Dep. Ent was a 
dependent class it could contain references to Foo. this (the parent of its parent) 
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or Dep. this (the latter being the same as specifying parent). If preferred, the full 
name or the fully qualified name of the parent class may be used instead of the short 
name. 

Like parent, this construct can only be used at the start of a term in non-static 
contexts in a dependent class. 

As usual, properties external to the current class must always be qualified in some 
way (for example, the prefix parent. can be used in a term such as parent. aprop). 


38.3 Restrictions 


Minor classes may have any of the attributes (public, interface, etc.) of other classes, 
and behave in every way like other classes, with the following restrictions: 


If a class is a static class (that is, it contains only static or constant properties and 
methods) then any children cannot be dependent classes (because no object of the 
parent class can be constructed). Similarly, interface classes and abstract classes 
cannot have dependent classes. 

Dependent classes may not be interfaces. 

Dependent classes may not contain static or constant properties (or methods). 
These must be placed in a parent which is not a dependent class. 

Minor classes may be public only if their parent is also public. (Note that this is the 
only case where more than one public class is permitted in a program.) In general: 
a minor class cannot be more visible than its parent. 





61 This restriction allows compilation for the Java platform. 
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Special names and methods 


For convenience, NetRExx provides some special names for naming commonly-used 
concepts within terms. These are only recognized if there is no variable of the same name 
previously seen in the current scope, as described in the section on Terms (see page 
. This allows the set of special words to be expanded in the future, if necessary, without 
invalidating existing variables. Therefore, these names are not reserved; they may be used 
as variable names instead, if desired. 


There are also two "special methods” that are used when constructing objects. 


39.1 Special names 


The following special names are allowed in NetRExx programs, and are recognized in- 
dependently of case. 4 With the exception of length and class, these may only be used 
alone as a term or at the start of a compound term. 


ask Returns a string of type REXx, read as a line from the implementation-defined de- 
fault input stream (often the user’s *console”). 
Example: 


if ask=’yes’ then say ’OK’ 
ask can only appear alone, or at the start of a compound term. & 

class The object of type Class that describes a specific type. This word is only recognized 
as the second part of a compound term, where the evaluation of the first part of the 


term resulted in a type or qualified type. 
Example: 


obj=String.class 
say obj.isInterface /* would say ’0’ x/ 


digits The current setting of numeric digits (see page , returned as a string of 
type Rexx. This will be one or more Arabic numerals, with no leading blanks, zeros, 
or sign, and no trailing blanks or exponent. digits can only appear alone, or at the 
start of a compound term. 

form The current setting of numeric form (see page {101} , returned as a string of type 
Rexx. This will have either the value ’scientific” or the value ’engineering”. form 
can only appear alone, or at the start of a compound term. 

length The length of an array (see page 62) , returned as an implementation-dependent 
binary type or string. This word is only recognized as the last part of a compound 





© Unless options strictcase is in effect. 
63 In the reference implementation, ask is simply a shorthand for REXxIO.Ask(). 
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term, where the evaluation of the rest of the term resulted in an array of dimension 
1. 
Example: 


foo=char [7] 
say foo.length /* would say ’7’ x*/ 


Note that you can get the length of a NetRExx string with the same syntax. 
In that case, however, a length() method is being invoked. 


null The empty reference. This is a special value that represents "no value” and may be 
assigned to variables (or returned from methods) except those whose type is both 
primitive and undimensioned. It may also be be used in a comparison for equality 
(or inequality) with values of suitable type, and may be given a type. Examples: 


blob=int[3] -- ’?blob’ refers to array of 3 ints 
blob=null -- ’?blob’ is still of type int[], 

-- but refers to no real object 
mob=Mark null -- ’mob’ is type ’Mark’ 


The null value may be considered to represent the state of being uninitialized. It 
can only appear as simple symbol, not as a part of a compound term. 


source Returns a string of type RExx identifying the source of the current class. The 
string consists of the following words, with a single blank between the words and 
no trailing or leading blanks: 
1. the name of the underlying environment (e.g., Java) 
2. either method (if the term is being used within a method) or class (if the term 
is being used within a property assignment, before the first method in a class) 
3. an implementation-dependent representation of the name of the source stream 
for the class (e.g., Fred.nrx). 
source can only appear alone, or at the start of a compound term. 


sourceline The line number of the first token of the current clause in the NetRExx pro- 
gram, returned as a string of type RExx. This will be one or more Arabic numerals, 
with no leading blanks, zeros, or sign, and no trailing blanks or exponent. source- 
line can only appear alone, or at the start of a compound term. 


super Returns a reference to the current object, with a type that is the type of the class 
that the current object’s class extends. This means that a search for methods or 
properties which super qualifies will start from the superclass rather than in the 
current class. This is used for invoking a method or property (in the superclass or 
one of its superclasses) that has been overridden in the current class. Example: 


method printit(x) 
say ’it’ -- modification 
super.printit(x) -- now the usual processing 


If a property being referenced is in fact defined by a superclass of the current class, 
then the prefix “super.” is perhaps the clearest way to indicate that name refers to 
a property of a superclass rather than to a local variable. (You could also qualify 
it by the name of the superclass.) super can only appear alone, or at the start of a 
compound term. 





64 Unless options strictargs is in effect. 
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this Returns a reference to the current object. When a method is invoked, for example 


in: 
word=Rexx ”hello” -- ’word’ refers to ”hello” 
say word.substr(3) -- invokes substr on ”hello” 


then the method substr in the class RExx is invoked, with argument ’3’, and with 
the properties of the value (object) ”hello” available to it. These properties may be 
accessed simply by name, or (more explicitly) by prefixing the name with ”this.”. 
Using *this.” can make a method more readable, especially when several objects of 
the same type are being manipulated in the method. this can only appear alone, or 
at the start of a compound term. 

trace The current trace (see page setting, returned as a NetRExx string. This will 
be one of the words: 


off var methods all results 


(var is returned when clause tracing is off but variable tracing has then been turned 
on using a trace var instruction.) trace can only appear alone, or at the start of a 
compound term. 

version Returns a string of type RExx identifying the version of the NetRExx language 
in effect when the current class was processed. ‘The string consists of the following 
words, with a single blank between the words and no trailing or leading blanks: 

1. A word describing the language. The first seven letters will be the characters 
NetRExx, and the remainder may be used to identify a particular implemen- 
tation or language processor. This word may not include any periods. 

2. The language level description, which must be a number with no sign or expo- 
nential part. For example, ” 3.07-BETA” is the language level of this definition. 

3. Three words describing the language processor release date in the same format 
as the default for the RExx ”date()” function. & For example, ”22 May 2009”. 

version can only appear alone, or at the start of a compound term. 


39.2 Special methods 


Constructors (methods used for constructing objects) in NetRExx must invoke a con- 
structor of their superclass before making any modifications to the current object (or 
invoke another constructor in the current class). 


This is simplified and made explicit by the provision of the special method names su- 
per and this, which refer to constructors of the superclass and current class respectively. 
These special methods are only recognized when used as the first, method call, instruc- 
tion in a constructor, as described in Methods and constructors (see page B7) . Their 
names will be recognized independently of case. £8 


In addition, NetRExx provides special constructor methods for the primitive types that 
allow binary construction of primitives. These are described in Binary values and arith- 


metic (see page {167). 





6 As defined in :cit.American National Standard for Information Technology - Programming Language REXX, X3.274-1996:ecit., 
American National Standards Institute, New York, 1996. 
66 Unless options strictcase is in effect. 
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JavaBean Support 


This chapter describes the indirect properties feature. 


The intention of this feature is to make it easier to write a certain kind of class known as 
a JavaBean. Almost all JavaBeans will have properties, which are data items that a user of 
a JavaBean is expected to be able to customize (for example, the text on a pushbutton). 
The names and types of the properties of a JavaBean are inferred from "design patterns” 
(in this context, conventions for naming methods) or from PropertyDescriptor objects 
associated with the JavaBean. 


The JavaBean properties do not necessarily correspond to instance variables in the class - 
although very often they do. The JavaBean specification does not guarantee that JavaBean 
properties that can be set can also be inspected, nor does it describe how ambiguities of 
naming and method signatures are to be handled. 


The NetRExxC compiler allows a more rigorous treatment of JavaBean properties, by 
allowing an optional attribute of properties in a class that declares them to be indirect 
properties. Indirect properties are properties of a known type that are private to the class, 
but which are expected to be publicly accessible indirectly, though certain conventional 
method calls. 


Declaring properties to be indirect offers the following advantages: 


¢ For many simple cases, the access methods for the properties can be generated au- 
tomatically; there is no need to explicitly code them in the source file for the class. 
This is especially helpful for Indexed Properties (where four methods are needed, 
in general). 

¢ Where access methods are explicitly provided in the class, they can be checked for 
correct form, signature and accessibility. This detects errors at compile time that 
otherwise would only be determined by testing. 


¢ Similarly, attention can be drawn to the presence of methods that may be intended 
to be an access method for an indirect property, but will not be recognized as such 
by builders. 


The next section describes the use of indirect properties in more detail. 


40.1 Indirect properties 


The properties instruction (see page |111) is used to define the attributes of following 
property variables. The visibility of properties may include a new alternative: indirect. 
Properties with this form of visibility are known as indirect properties. These are proper- 
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ties of a known type that are private to the class, but which are expected to be publicly 
accessible indirectly, though certain conventional method calls. 


For example, consider the simple program: 


Listing 40.1: Sandwich.nrx 


class Sandwich extends Canvas implements Serializable 
properties indirect 
slices=Color.gray 
filling=Color.red 


method Sandwich 
resize(100,30) 


method paint(g=Graphics) 
g.setColor (slices) 
g.fillRect(0, 0, size.width, size.height) 
g.setColor (filling) 
g.fillRect(12, 12, size.width-12, size.height-12) 


This declares the Sandwich class as having two indirect properties, called slices and 
filling, both being of type java.awt.Color. 


In the example, no access methods are provided for the properties, so the compiler will 
add them. By implementation-dependent convention, the names are prefixed with verbs 
such as get and set, etc., and have the first character of their name uppercased to form 
the method names. Hence, in this Java-based example, the following four methods are 
added: 


Listing 40.2: Slices 


method getSlices returns java.awt.Color 
return slices 

method getFilling returns java.awt.Color 
return filling 

method setSlices($1l=java.awt.Color) 
slices=$1 

method setFilling($2=java.awt.Color) 
filling=$2 


(where $1 and $2 are hidden” names used for accessing the method arguments). 


Note that the indirect attribute for a property is an alternative to the public, private, 
and inheritable, and shared attributes. Like private properties, indirect properties can 
only be accessed directly by name from within the class in which they occur; other classes 
can only access them using the access methods (or other methods that may use, or have 
a side-effect on, the properties). 


Indirect properties may be constant (implying that only a get method is generated or 
allowed, though the private property may be changed by methods within the class) or 
transient (see page |112)) . They may not be static or volatile. 

In detail, the rules used for generating automatic methods for a property whose name is 
xxxx are as follows: 


1. A method called getXxxx which returns the value of the property is generated. The 
returned value will have the same type as xxxx. 


2. If the type of xxxx is boolean then the generated method will be called isXxxx 
instead of getXxxx. 
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3. If the property is not constant then a method for setting the property will also be 
generated. This will be called setXxxx, and take a single argument of the same type 
as xxxx. This assigns the argument to the property and returns no value. 


If the property has an array type (for example, char[]), then it must only have a single 
dimension. Two further methods may then be generated, according to the rules: 


1. A method called getXxxx which takes a single int as an argument and which re- 
turns an item from the property array is generated. The returned value will have 
the same type as xxxx, without the []. The integer argument is used to index into 
the array. 

2. As before, if the result type of the method would be boolean then the name of the 
method will be isXxxx instead of getXxxx. 

3. If the property is not constant then a method for setting an item in the property 
array will also be generated. This will be called setXxxx, and take two arguments: 
the first is an int that is used to select the item to be changed, and the second is an 
undimensioned argument of the same type as xxxx. It assigns the second argument 
to the item in the property array indexed by the first argument, and returns no 
value. 


For example, for an indirect property declared thus: 


properties indirect 
fred=foo.Bar[] 


the four methods generated would be: 


Listing 40.3: getFred/setFred 


method getFred returns foo.Bar[]; return fred 

method getFred($1=int) returns foo.Bar; return fred[$1] 
method setFred($2=foo.Bar[]); fred=$2 

method setFred($3=int, $4=foo.Bar); fred[$3]=$4 


Note that in all cases a method will only be generated if it would not exactly match a 
method explicitly coded in the current class. 


40.1.1 Explicit provision of access methods 


Often, for example when an indirect property has an on-screen representation, it is de- 
sirable to redraw the property when the property is changed (and in more complicated 
cases, there may be interactions between properties). These and other actions will re- 
quire extra processing which will not be carried out by automatically generated meth- 
ods. To add this processing the access methods will have to be coded explicitly. In the 
*Sandwich” example, we only need to supply the set methods, perhaps by adding the 
following to the example class above: 


Listing 40.4: setSlices 


method setSlices(col=Color) 
slices=col -- update the property 
this.repaint -- redraw the component 


method setFilling(col=Color) 


145 


6 
7 


filling=col 
this.repaint 


If we add these two methods, they will no longer be added automatically (the two get 
methods will continue to be provided automatically, however). Further, since the names 
match possible access methods for properties that are declared to be indirect, the com- 
piler will check the method declaration: the method signatures and return type (if any) 
must be correct, for example. Also, since the names of access methods are case-sensitive 
(in a Java environment), you will be warned if a method appears to be intended to be an 
access method but the case of one or more letters is wrong. 


Specifically, the checks carried out are as follows: 


1. For methods whose names exactly match a potential access method for an indirect 
property (that is, start with is, get, or set, which is then followed by the name of an 
indirect property with the first character of the name uppercased): 

The argument list for (signature of) the method must match one of those that 

could possibly be automatically generated for the property. 

The returns type (if any) must match the expected returns type for that 

method. 

If the returns type is simply boolean, then the method name must start with 

is. Conversely, if the method name starts with is then the returns type must be 

just boolean. 

If the property is constant then the name of the method cannot start with set. 

A warning is given if the method is not public (the default). 


2. For methods whose names match a potential access method, as above, except in 
case: 

« A warning is given that the method in question may be intended to be an in- 

direct property access method, but will not be recognized as such by builders. 


These checks detect a wide variety of errors at compile time, hence speeding the devel- 
opment of classes that use indirect properties. 
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Parsing templates 


The parse instruction allows a selected string to be parsed (split up) and assigned to 
variables, under the control of a template. 


‘The various mechanisms in the template allow a string to be split up by explicit matching 
of strings (called patterns), or by specifying numeric positions (positional patterns - for 
example, to extract data from particular columns ofa line read from a character stream). 
Once split into parts, each segment of the string can then be assigned to variables as a 
whole or by words (delimited by blanks). 


This section first gives some informal examples of how the parsing template can be used, 
and then defines the algorithms in detail. 


41.1 Introduction to parsing 


The simplest form of parsing template consists of a list of variable names. ‘The string being 
parsed is split up into words (characters delimited by blanks), and each word from the 
string is assigned to a variable in sequence from left to right. The final variable is treated 
specially in that it will be assigned whatever is left of the original string and may therefore 
contain several words. For example, in the parse instruction: 


parse ’This is a sentence.’ vl v2 v3 


the term (in this case a literal string) following the instruction keyword is parsed, and 
then: the variable v1 would be assigned the value ”This’, v2 would be assigned the value 


De 


is’, and v3 would be assigned the value ”a sentence.”. 


Leading blanks are removed from each word in the string before it is assigned to a vari- 
able, as is the blank that delimits the end of the word. Thus, variables set in this manner 
(v1 and v2 in the example) will never have leading or trailing blanks, though v3 could 
have both leading and trailing blanks. Note that the variables assigned values in a tem- 
plate are always given a new value and so if there are fewer words in the string than 
variables in the template then the unused variables will be set to the null string. The sec- 
ond parsing mechanism uses a literal string in a template as a pattern, to split up the 
string. For example: 


parse ’To be, or not to be?’ wl ’,’ w2 


would cause the string to be scanned for the comma, and then split at that point; the 
variable w1 would be set to ”To be’, and w2 is set to ” or not to be?”. Note that the 
pattern itself (and only the pattern) is removed from the string. Each section of the string 
is treated in just the same way as the whole string was in the previous example, and so 
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either section could be split up into words. Thus, in: 
parse ’To be, or not to be?’ wl ’,’ w2 w3 w4 


w2 and w3 would be assigned the values ”or” and ’not’, and w4 would be assigned the 
remainder: ”to be?” 


If the string in the last example did not contain a comma, then the pattern would effec- 
tively *match” the end of the string, so the variable to the left of the pattern would get 
the entire input string, and the variables to the right would be set to a null string. The 
pattern may be specified as a variable, by putting the variable name in parentheses. The 
following instructions therefore have the same effect as the last example: 


Ga,” 
parse ’To be, or not to be?’ wil (c) w2 w3 w4 


The third parsing mechanism is the numeric positional pattern. This works in the same 
way as the string pattern except that it specifies a column number. So: 


parse ’Flying pigs have wings’ x15 x2 


would split the string at the fifth column, so x1 would be ”Flyi” and x2 would start 
at column 5 and so be ’ng pigs have wings”. More than one pattern is allowed, so for 
example: 


parse ’Flying pigs have wings’ x1 5 x2 10 x3 


would split the string at columns 5 and 10, so x2 would be "ng pi” and x3 would be ’gs 
have wings”. The numbers can be relative to the last number used, so: 


parse ’Flying pigs have wings’ x1 5 x2 +5 x3 


would have exactly the same effect as the last example; here the +5 may be thought of 
as specifying the length of the string to be assigned to x2. As with literal string patterns, 
the positional patterns can be specified as a variable by putting the name of a variable, 
in parentheses, in place of the number. An absolute column number should then be 


indicated by using an equals sign (”=”) instead of a plus or minus sign. The last example 
could therefore be written: 


start=5 

length=5 

data=’Flying pigs have wings’ 

parse data x1 =(start) x2 +(length) x3 


String patterns and positional patterns can be mixed (in effect the beginning of a string 
pattern just specifies a variable column number) and some very powerful things can be 
done with templates. The next section describes in more detail how the various mecha- 
nisms interact. 
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41.2 Parsing definition 


This section describes the rules that govern parsing. In its most general form, a template 
consists of alternating pattern specifications and variable names. Blanks may be added 
between patterns and variable names to separate the tokens and to improve readabil- 
ity. The patterns and variable names are used strictly in sequence from left to right, and 
are used once only. In practice, various simpler forms are used in which either variable 
names or patterns may be omitted; we can therefore have variable names without pat- 
terns in between, and patterns without intervening variable names. In general, the value 
assigned to a variable is that sequence of characters in the input string between the point 
that is matched by the pattern on its left and the point that is matched by the pattern on 
its right. If the first item in a template is a variable, then there is an implicit pattern on 
the left that matches the start of the string, and similarly if the last item in a template 
is a variable then there is an implicit pattern on the right that matches the end of the 
string. Hence the simplest template consists of a single variable name which in this case 
is assigned the entire input string. Setting a variable during parsing is identical in ef- 
fect to setting a variable in an assignment. The constructs that may appear as patterns 
fall into two categories; patterns that act by searching for a matching string (literal pat- 
terns), and numeric patterns that specify an absolute or relative position in the string 
(positional patterns). Either of these can be specified explicitly in the template, or al- 
ternatively by a reference to a variable whose value is to be used as the pattern. For the 
following examples, assume that the following sample string is being parsed; note that 
all blanks are significant - there are two blanks after the first word ”is” and also after the 
second comma: 


"This is the text which, I think, is scanned.’ 


41.2.1 Parsing with literal patterns 


Literal patterns cause scanning of the data string to find a sequence that matches the 
value of the literal. Literals are expressed as a quoted string. The null string matches the 
end of the data. The template: 


wl ’,’ w2 ’,’ w3 
when parsing the sample string, results in: 


wl has the value ”This is the text which” 
w2 has the value ” I think” 
w3 has the value ” is scanned.” 


Here the string is parsed using a template that asks that each of the variables receive a 
value corresponding to a portion of the original string between commas; the commas 
are given as quoted strings. Note that the patterns themselves are removed from the data 
being parsed. A different parse would result with the template: 


wl ’,’ w2 ’,’ w3 ’,’ w4 
which would result in: 
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wl has the value ”This is the text which” 
w2 has the value ” I think” 

w3 has the value ” is scanned.” 

w4 has the value ”” (null string) 


This illustrates an important rule. When a match for a pattern cannot be found in the 
input string, it instead *matches” the end of the string. Thus, no match was found for the 
third >? in the template, and so w3 was assigned the rest of the string. w4 was assigned a 
null string because the pattern on its left had already reached the end of the string. Note 
that all variables that appear in a template in this way are assigned a new value. 


41.2.2 Parsing strings into words 


Ifa variable is directly followed by one or more other variables, then the string selected by 
the patterns is assigned to the variables in the following manner. Each blank-delimited 
word in the string is assigned to each variable in turn, except for the last variable in the 
group (which is assigned the remainder of the string). The values of the variables which 
are assigned words will have neither leading nor trailing blanks. Thus the template: 


wl w2 w3 w4 ’,’ 
would result in: 


wl has the value ”This’ 

w2 has the value ”is” 

w3 has the value ”the” 

w4 has the value ”text which” 


Note that the final variable (w4 in this example) could have had both leading blanks and 
trailing blanks, since only the blank that delimits the previous word is removed from 
the data. Also observe that this example is not the same as specifying explicit blanks as 
patterns, as the template: 


wl’? ? w2 ’? ’ w3 ” ° w4 ’,?’ 
would in fact result in: 


wl has the value ”This’ 

w2 has the value ”is” 

w3 has the value ”” (null string) 
w4 has the value ”the text which” 


since the third pattern would match the third blank in the data. In general, when a vari- 
able is followed by another variable then parsing of the input into individual words is 
implied. The parsing process may be thought of as first splitting the original string up 
into other strings using the various kinds of patterns, and then assigning each of these 
new strings to (zero or more) variables. 
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41.2.3 Use of the period as a placeholder 


A period (separated from any symbols by at least one blank) acts as a placeholder in a 
template. It has exactly the same effect as a variable name, except that no variable is set. 
It is especially useful as a "dummy variable” in a list of variables, or to collect (ignore) 
unwanted information at the end ofa string. Thus the template: 


. word4 . 


would extract the fourth word ("text”) from the sample string and place it in the variable 
word4. Blanks between successive periods in templates may be omitted, so the template: 


. word4 . 


would have the same result as the last template. 


41.2.4 Parsing with positional patterns 


Positional patterns may be used to cause the parsing to occur on the basis of position 
within the string, rather than on its contents. They take the form of whole numbers, 
optionally preceded by a plus, minus, or equals sign which indicate relative or absolute 
positioning. These may cause the matching operation to ’back up” to an earlier position 
in the data string, which can only occur when positional patterns are used. Absolute 
positional patterns: A number in a template that is not preceded by a sign refers to a 
particular (absolute) character column in the input, with 1 referring to the first column. 
For example, the template: 


s1 10 s2 20 s3 
results in: 


sl has the value ”This is ” 
s2 has the value ”the text w” 
s3 has the value "hich, I think, is scanned.” 


Here s1 is assigned characters from the first through the ninth character, and s2 receives 
input characters 10 through 19. As usual the final variable, s3, is assigned the remainder 
of the input. 


b> a>) 


An equals sign (”=”) may be placed before the number to indicate explicitly that it is to 
be used as an absolute column position; the last template could have been written: 


sl =10 s2 =20 s3 


A positional pattern that has no sign or is preceded by the equals sign is known as an 
absolute positional pattern. Relative positional patterns: A number in a template that is 
preceded by a plus or minus sign indicates movement relative to the character position at 
which the previous pattern match occurred. This is a relative positional pattern. If a plus 
or minus is specified, then the position used for the next match is calculated by adding 
(or subtracting) the number given to the last matched position. The last matched position 
is the position of the first character of the last match, whether specified numerically or 
by a string. 
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For example, the instructions: 
parse °123456789’ 3 wl +3 w2 3 w3 
result in 


wl has the value ”345” 
w2 has the value ”6789” 
w3 has the value ”3456789” 


The +3 in this case is equivalent to the absolute number 6 in the same position, and may 
also be considered to be specifying the length of the data string to be assigned to the 
variable w1. This example also illustrates the effects of a positional pattern that implies 
movement to a character position to the left of (or to) the point at which the last match 
occurred. The variable on the left is assigned characters through the end of the input, and 
the variable on the right is, as usual, assigned characters starting at the position dictated 
by the pattern. A useful effect of this is that multiple assignments can be made: 


parse x 1 wl 1 w2 1 w3 


This results in assigning the (entire) value of x to w1, w2, and w3. (‘The first ”1” here could 
be omitted as it is effectively the same as the implicit starting pattern described at the 
beginning of this section.) If a positional pattern specifies a column that is greater than 
the length of the data, it is equivalent to specifying the end of the data (i.e., no padding 
takes place). Similarly, ifa pattern specifies a column to the left of the first column of the 
data, this is not an error but instead is taken to specify the first column of the data. Any 
pattern match sets the “last position” in a string to which a relative positional pattern 
can refer. The last position” set by a literal pattern is the position at which the match 
occurred, that is, the position in the data of the first character in the pattern. The literal 
pattern in this case is not removed from the parsed data. Thus the template: 


yo 1 9-41 
will: 


1. Find the first comma in the input (or the end of the string if there is no comma). 

2. Back up one position. 

3. Assign one character (the character immediately preceding the comma or end of 
string) to the variable x. 


One possible application of this is looking for abbreviations in a string. Thus the instruc- 
tion: 


/x Ensure options have a leading blank and are 
in uppercase before parsing. x/ 
parse (’ ’opts).upper ’ PR’ +1 prword ’ ’ 


will set the variable prword to the first word in opts that starts with ”PR” (in any case), 
or will set it to the null string if no such word exists. Notes: 


1. The positional patterns +0 and -0 are valid, have the same effect, and may be used 
to include the whole of a previous literal (or variable) pattern within the data string 
to be parsed into any following variables. 
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2. As illustrated in the last example, patterns may follow each other in the template 
without intervening variable names. In this case each pattern is obeyed in turn from 
left to right, as usual. 

3. There may be blanks between the sign in a positional pattern and the number, be- 
cause NetRExx defines that blanks adjacent to special characters are removed. 


41.2.5 Parsing with variable patterns 


It is sometimes desirable to be able to specify a pattern by using the value of a variable 
instead of a fixed string or number. This may be achieved by placing the name of the 
variable to be used as the pattern in parentheses (blanks are not necessary either inside or 
outside the parentheses, but may be added if desired). This is called a variable reference; 
the value of the variable is converted to string before use, if necessary. If the parenthesis 


to the left of the variable name is not preceded by an equals, plus, or minus sign ("=", +’, 


or ”-”) the value of the variable is then used as though it were a literal (string) pattern. 
The variable may be one that has been set earlier in the parsing process, so for example: 


input=”"L/look for/1 10” 
parse input verb 2 delim +1 string (delim) rest 


will set: 


verb to ’L’ 

delim to ’/’ 

string to ’look for’ 
rest to ’?1 10’ 


If the left parenthesis is preceded by an equals, plus, or minus sign then the value of the 
variable is used as an absolute or relative positional pattern (instead of as a literal string 
pattern). In this case the value of the variable must be a non-negative whole number, and 
(as before) it may have been set earlier in the parsing process. 
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42 





Numbers and Arithmetic 


NetRexx arithmetic attempts to carry out the usual operations (including addition, sub- 
traction, multiplication, and division) in as “natural” a way as possible. What this really 
means is that the rules followed are those that are conventionally taught in schools and 
colleges. However, it was found that unfortunately the rules used vary considerably (in- 
deed much more than generally appreciated) from person to person and from applica- 
tion to application and in ways that are not always predictable. The NetRExx arithmetic 
described here is therefore a compromise which (although not the simplest) should pro- 
vide acceptable results in most applications. 


42.1 Introduction 


Numbers can be expressed in NetRExx very flexibly (leading and trailing blanks are 
permitted, exponential notation may be used) and follow conventional syntax. Some 
valid numbers are: 


12 /*x A whole number *x/ 
>-76? /* A signed whole number x/ 
12.76 /* Some decimal places x/ 

> + 0.003 ’ /x Blanks around the sign, etc. x/ 
17. /x Equal to 17 x/ 
5? /*x Equal to 0.5 */ 

A4E+9 /* Exponential notation x/ 
0.73e-7 /* Exponential notation x/ 


(Exponential notation means that the number includes a sign and a power of ten fol- 
lowing an ”E” that indicates how the decimal point will be shifted. Thus 4E+9 above is 
just a short way of writing 4000000000, and 0.73e-7 is short for 0.000000073.) The 
arithmetic operators include addition (indicated by a”+”), subtraction (”-”), multiplica- 
tion (°*”), power (”**”), and division (”/”). There are also two further division operators: 
integer divide (”%”) which divides and returns the integer part, and remainder (”//”) 
which divides and returns the remainder. Prefix plus (°+”) and prefix minus (”-”) op- 
erators are also provided. When two numbers are combined by an operation, NetREXx 
uses a set of rules to define what the result will be (and how the result is to be represented 
as a character string). These rules are defined in the next section, but in summary: 


¢ Results will be calculated with up to some maximum number of significant digits. 
That is, if a result required more than 9 digits it would normally be rounded to 9 
digits. For instance, the division of 2 by 3 would result in 0.666666667 (it would 
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require an infinite number of digits for perfect accuracy). 

You can change the default of 9 significant digits by using the numeric digits 
instruction. This lets you calculate using as many digits as you need - thousands, if 
necessary. 


¢ Except for the division and power operators, trailing zeros are preserved (this is 
in contrast to most electronic calculators, which remove all trailing zeros in the 
decimal part of results). So, for example: 


2.40 +2 => 4.40 


2.40 - 2 => 0.40 
2.40 * 2 => 4.80 
2.40 / 2 => 1.2 


This preservation of trailing zeros is desirable for most calculations (and especially 
financial calculations). If necessary, trailing zeros may be easily removed with the 
strip method (see page |191)) , or by division by 1. 


« A zero result is always expressed as the single digit ’0’. 


Exponential form is used for a result depending on its value and the setting of 
numeric digits (the default is 9 digits). If the number of places needed before 
the decimal point exceeds this setting, or the absolute value of the number is less 
than 0.000001, then the number will be expressed in exponential notation; thus 


let+6 x let+6é 

results in ”1E+12” instead of 1000000000000”, and 

1 / 3E+10 

results in ”3.33333333E-11” instead of ”0.0000000000333333333”. 


¢ Any mixture of Arabic numerals (0-9) and Extra digits (see page 21) can be used for 
the digits in numbers used in calculations. The results are expressed using Arabic 
numerals. 


42.2 Definition 


This definition describes arithmetic for NetRExx strings (type RExx). The arithmetic 
operations are identical to those defined in the ANSI standard for Rexx. 4 


42.2.1 Numbers 


A number in NetRExx is a character string that includes one or more decimal digits, with 
an optional decimal point. The decimal point may be embedded in the digits, or may be 
prefixed or suffixed to them. The group of digits (and optional point) thus constructed 
may have leading or trailing blanks, and an optional sign (”+” or ”-”) which must come 
before any digits or decimal point. The sign may also have leading or trailing blanks. 


Thus: 





67 :cit. American National Standard for Information Technology - Programming Language REXX, X3.274-1996:ecit., American 
National Standards Institute, New York, 1996. 
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sign fro 4 [= 


digit 2= Of] 1]2/3/4/5]6]7]18e|9 
digits ::= digit [digit]... 
numeric ::= digits . [digits] 
| [.] digits 
number ::= [blank]... [sign [blank]...] 


numeric [blank]... 


where if the implementation supports extra digits (see page 21]) these are also accepted 
as digits, providing that they represent values in the range zero through nine. In this case 
each extra digit is treated as though it were the corresponding character in the range 0-9. 
Note that a single period alone is not a valid number. 


42.2.2 Precision 


The maximum number of significant digits that can result from an arithmetic operation 
is controlled by the digits keyword on the numeric instruction (see page {101} : 


numeric digits [expression]; 


The expression is evaluated and must result in a positive whole number. This defines the 
precision (number of significant digits) to which arithmetic calculations will be carried 
out; results will be rounded to that precision, if necessary. If no expression is specified, 
then the default precision is used. The default precision is 9, that is, all implementations 
must support at least nine digits of precision. An implementation-dependent maximum 
(equal to or larger than 9) may apply: an attempt to exceed this will cause execution of the 
instruction to terminate with an exception. Thus if an algorithm is defined to use more 
than 9 digits then ifthe numeric digits instruction succeeds then the computation will 
proceed and produce identical results to any other implementation. Note that numeric 
digits may set values below the default of nine. Small values, however, should be used 
with care - the loss of precision and rounding thus requested will affect all NetRExx 
computations, including (for example) the computation of new values for the control 
variable in loops. 


In the remainder of this section, the notation digits refers to the current setting of 
numeric digits. This setting may also be referred to in expressions in programs by 
using the digits special word (see page 139) . 


42.2.3. Arithmetic operators 


NetReExx arithmetic is effected by the operators ”+", ”-”,°) "7, °%°, "//, and ”**” (add, 
subtract, multiply, divide, integer divide, remainder, and power) which all act upon two 
terms, together with the prefix operators ”+” and ”-” (plus and minus) which both act on 
a single term. The result of all these operations is a NetRExx string, of type RExx. This 
section describes the way in which these operations are carried out. Before every arith- 
metic operation, the term or terms being operated upon have any extra digits converted 
to the corresponding Arabic numeral (the digits 0-9). They then have leading zeros re- 
moved (noting the position of any decimal point, and leaving just one zero if all the digits 
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in the number are zeros) and are then truncated to digits+1 significant digits © (if neces- 
sary) before being used in the computation. The operation is then carried out under up 
to double that precision, as described under the individual operations below. When the 
operation is completed, the result is rounded if necessary to the precision specified by 
the numeric digits instruction. Rounding is done in the ”traditional” manner, in that 
the extra (guard) digit is inspected and values of 5 through 9 are rounded up, and values 
of 0 through 4 are rounded down. & A conventional zero is supplied preceding a deci- 
mal point if otherwise there would be no digit before it. Trailing zeros are retained for 
addition, subtraction, and multiplication, according to the rules given below, except that 
a result of zero is always expressed as the single character ’0’. For division, insignificant 
trailing zeros are removed after rounding. 


The format method (see page is defined to allow a number to be represented in 
a particular format if the standard result provided by NetRExx does not meet require- 
ments. 


42.2.4 Arithmetic operation rules - basic operators 


The basic operators (addition, subtraction, multiplication, and division) operate on 
numbers as follows: 


Addition and subtraction If either number is zero then the other number, rounded to 
digits digits if necessary, is used as the result (with sign adjustment as appropriate). 
Otherwise, the two numbers are extended on the right and left as necessary up to 
a total maximum of digits+1 digits. 

The number with smaller absolute value may therefore lose some or all of its dig- 
its on the right. 2 The numbers are then added or subtracted as appropriate. For 
example: 


XXXX.XXX + YY. yyyyy 
becomes: 


XXXX.XXX00 
+ OOyy.yyyyy 


ZZZZ.ZZZZZ 


.sumadd The result is then rounded to digits digits if necessary, taking into account 
any extra (carry) digit on the left after an addition, but otherwise counting from the 
position corresponding to the most significant digit of the terms being added or 
subtracted. Finally, any insignificant leading zeros are removed. The prefix operators 
are evaluated using the same rules; the operations ’+number” and ”-number” are 
calculated as ”0+number” and ”0-number’, respectively. 

Multiplication The numbers are multiplied together ("long multiplication”) resulting 
in a number which may be as long as the sum of the lengths of the two operands. 
For example: 





68 That is, to the precision set by numeric digits, plus one extra “guard” digit. 

6 Even/odd rounding would require the ability to calculate to arbitrary precision (that is, to a precision not governed by the 
setting of numeric digits) at any time and is therefore not the mechanism defined for NetRExx. 

70 Tn the example, the number yy.yyyyy would have three digits truncated if digits were 5. 
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XXX.XXX * yy. yyyyy 
becomes: 
ZZZZZ.ZZZZZZZZ 


and the result is then rounded to digits digits if necessary, counting from the first 
significant digit of the result. 


Division For the division: 


yyy / XXXxx 


the following steps are taken: first, the number ”yyy” is extended with zeros on the 
right until it is larger than the number ”xxxxx” (with note being taken of the change 
in the power of ten that this implies). Thus in this example, *yyy” might become 
*yyy00”. Traditional long division then takes place, which can be written: 


XXXxx | yyy0O 


b> yam) 


The length of the result (°zzzz”) is such that the rightmost ”z” will be at least as 
far right as the rightmost digit of the (extended) ”y” number in the example. Dur- 
ing the division, the ”y” number will be extended further as necessary, and the ”z” 
number (which will not include any leading zeros) may increase up to digits+1 
digits, at which point the division stops and the result is rounded. Following com- 
pletion of the division (and rounding if necessary), insignificant trailing zeros are 


removed. 


Examples: 


/x With ’numeric digits 5’ x/ 


12+7.00 == 19.00 
1.3-1.07 == 0123 
1.3-2.07 == -0.77 
1.20*3 == 3.60 
7x3 Be OF 
0.9*0.8 == 0.72 
1/3 == Q,33333 
2/3 == 0.66667 
5/2 2S: 9S 
1/10 == 0.1 
12/12 ae | 

8.0/2 oS) a 


Note: With all the basic operators, the position of the decimal point in the terms being 
operated upon is arbitrary. The operations may be carried out as integer operations with 
the exponent being calculated and applied afterwards. ‘Therefore the significant digits of 
a result are not in any way dependent on the position of the decimal point in either of 
the terms involved in the operation. 
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42.2.5 Arithmetic operation rules - additional operators 


The operation rules for the power (”**”), integer division (’%”), and remainder (”//”) 
operators are as follows: 


Power The ”**” (power) operator raises a number (on the left of the operator) to a power 
(on the right of the operator). The term on the right is rounded to digits digits 
(if necessary), and must, after any rounding, be a whole number, which may be 
positive, negative, or zero. If negative, the absolute value of the power is used, and 
then the result is inverted (divided into 1). 
For calculating the power, the number is effectively multiplied by itself for the 
number of times expressed by the power, and finally trailing zeros are removed 
(as though the result were divided by one). In practice (see note below for the rea- 
sons), the power is calculated by the process of left-to-right binary reduction. For 
*x**n”: ’n” is converted to binary, and a temporary accumulator is set to 1. If ”n” 
has the value 0 then the initial calculation is complete. Otherwise each bit (starting 
at the first non-zero bit) is inspected from left to right. If the current bit is 1 then 
the accumulator is multiplied by ”x” If all bits have now been inspected then the 
initial calculation is complete, otherwise the accumulator is squared by multipli- 
cation and the next bit is inspected. When the initial calculation is complete, the 
temporary result is divided into 1 if the power was negative. 
The multiplications and division are done under the normal arithmetic operation 
rules, detailed earlier in this section, using a precision of digitstelength+1 digits. 
Here, elength is the length in decimal digits of the integer part of the whole number 
*n” (i.e., excluding any sign, decimal part, decimal point, or insignificant leading 
zeros, as though the operation n%1 had been carried out and any sign removed). 
Finally, the result is rounded to digits digits, if necessary, and insignificant trailing 
zeros are removed. 


Integer division The ”%” (integer divide) operator divides two numbers and returns 
the integer part of the result. The result returned is defined to be that which would 
result from repeatedly subtracting the divisor from the dividend while the dividend 
is larger than the divisor. During this subtraction, the absolute values of both the 
dividend and the divisor are used: the sign of the final result is the same as that 
which would result if normal division were used. The result returned will have no 
fractional part (that is, no decimal point or zeros following it). If the result can- 
not be expressed exactly within digits digits, the operation is in error and will fail 
- that is, the result cannot have more digits than the current setting of numeric 
digits. For example, 10000000000%3 requires ten digits to express the result ex- 
actly (3333333333) and would therefore fail if digits were 9 or smaller. 


Remainder The ”//” (remainder) operator will return the remainder from integer di- 
vision, and is defined as being the residue of the dividend after the operation of 
calculating integer division as just described. The sign of the remainder, if non- 
zero, is the same as that of the original dividend. This operation will fail under the 
same conditions as integer division (that is, if integer division on the same two 
terms would fail, the remainder cannot be calculated). 


Examples: 
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/x Again with ’numeric digits 5’ x/ 
2**3 == og 
2*x-3 == 0.125 
1.7*x8 == 69.758 
2%3 == 0 
2.1//3 == 2.1 
10%3 == 3 
10//3 == 1 
-10//3 SS <oll 
10.2//1 == 0.2 
10//0.3 == 0.1 
3.6//1.3 == 1.0 
Notes: 
1. A particular algorithm for calculating powers is described, since it is efficient 


42.2. 


Any 


(though not optimal) and considerably reduces the number of actual multipli- 
cations performed. It therefore gives better performance than the simpler defini- 
tion of repeated multiplication. Since results could possibly differ from those of 
repeated multiplication, the algorithm must be defined here so that different im- 
plementations will give identical results for the same operation on the same values. 
Other algorithms for this (and other) operations may always be used, so long as 
they give identical results to those described here. 


. The integer divide and remainder operators are defined so that they may be cal- 


culated as a by-product of the standard division operation (described above). The 
division process is ended as soon as the integer result is available; the residue of the 
dividend is the remainder. 


6 Numeric comparisons 


of the comparative operators (see page f9) may be used for comparing numeric 


strings. However, the strict comparisons (for example, ”==” and ”>>”) are not numeric 
comparative operators and should not normally be used for comparing numbers, since 


they 


compare from left to right and leading and trailing blanks (and leading zeros) are 


significant for these operators. Numeric comparison, using the normal comparative op- 
erators, is effected by subtracting the two numbers (calculating the difference) and then 
comparing the result with ’0’ - that is, the operation: 


A? 


B 


where ”?” is any normal comparative operator, is identical to: 


(A= 


B) ? ’Q’ 


It is therefore the difference between two numbers, when subtracted under NetRExx 
subtraction rules, that determines their equality. 


161 


42.2.7 Exponential notation 


The definition of numbers above (see page describes pure” numbers, in the sense 
that the character strings that describe numbers can be very long. Examples: 


say 10000000000 * 10000000000 
/* would display: 100000000000000000000 x/ 


say 0.00000000001 * 0.00000000001 
/* would display: 0.0000000000000000000001 «/ 


For both large and small numbers some form of exponential notation is useful, both 
to make such long numbers more readable and to make evaluation possible in extreme 
cases. In addition, exponential notation is used whenever the ’pure” form would give 
misleading information. For example: 


numeric digits 5 
say 54321*54321 


would display ”2950800000” if long form were to be used. This is misleading, as it ap- 
pears that the result is an exact multiple of 100000, and so NetRExx would express the 
result in exponential notation, in this case ”2.9508E+9”. The definition of number (see 
above) is therefore extended by replacing the description of numeric by the following: 


mantissa ::= digits . [digits] 
| [.] digits 
numeric ::= mantissa [E sign digits] 


In other words, the numeric part of a number may be followed by an ”E” (indicating 
an exponential part), a sign, and an integer following the sign that represents a power 
of ten that is to be applied. The ”E” may be in uppercase or lowercase. Note that no 
blanks are permitted within this part of a number, but the integer may have leading 
zeros. Examples: 


12E+11 = 1200000000000 
12E-5 = @©.00012 
12e+4 = 120000 


All valid numbers may be used as data for arithmetic. The results of calculations will be 
returned in exponential form depending on the setting of numeric digits. If the num- 
ber of places needed before the decimal point exceeds digits, or if the absolute value of 
the result is less than 0.000001, then exponential form will be used. The exponential 
form generated by NetRExx always has a sign following the ”E”. If the exponent is 0 then 
the exponential part is omitted - that is, an exponential part of ”E+0” will never be gen- 
erated. If the default format for a number is not satisfactory for a particular application, 
then the format method may be used to control its format. Using this, numbers may be 
explicitly converted to exponential form or even forced to be returned in ”pure” form. 

Different exponential notations may be selected with the numeric form instruction (see 
page . This instruction allows the selection of either scientific or engineering nota- 
tion. Scientific notation adjusts the power of ten so there is a single non-zero digit to the 
left of the decimal point. Engineering notation causes powers of ten to be expressed as a 
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multiple of three - the integer part may therefore range from 1 through 999. Examples: 


numeric form scientific 
say 123.45 x lell 
/*x would display: 1.2345E+13 x/ 


numeric form engineering 
say 123.45 »* lell 
/*x would display: 12.345E+12 x/ 


The default exponential notation is scientific. 


42.2.8 Whole numbers 


Within the set of numbers understood by NetRExx it is useful to distinguish the subset 
defined as whole numbers. 


A whole number in NetRExx is a number that has a decimal part which is all zeros (or 
that has no decimal part). 


42.2.9 Numbers used directly by NetREXx 


As discussed above, the result of any arithmetic operation is rounded (if necessary) ac- 
cording to the setting of numeric digits. Similarly, when a number (which has not 
necessarily been involved in an arithmetic operation) is used directly by NetRexx then 
the same rounding is also applied, just as though the operation of adding the number to 
0 had been carried out. After this operation, the integer part of the number must have 
no more digits than the current setting of numeric digits. 


In the following cases, the number used must be a whole number and an implementation 
restriction on the largest number that can be used may apply: 


* positional patterns, including variable positional patterns, in parsing templates (see 
page 

+ the power value (right hand operand) of the power operator (see page 160). 

* the values of exprr and exprf (following the for keyword) in the loop instruction 
(see page 

* the value of exprd (following the digits keyword) in the numeric instruction (see 


page [L01) . 


Implementation minimum: A minimum length of 9 digits must be supported for these 
uses of whole numbers by a NetRexx language processor. 


42.2.10 Implementation independence 


The NetRexx arithmetic rules are defined in detail, so that when a given program is run 
the results of all computations are sufficiently defined that the same answer will result 
for all correct implementations. Differences due to the underlying machine architecture 
will not affect computations. This contrasts with most other programming languages, 
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and with binary arithmetic (see page in NetRexx, where the result obtained may 
depend on the implementation because the precision and algorithms used by the lan- 
guage processor are defined by the implementation rather than by the language. 


42.2.11 Exceptions and errors 


The following exceptions and errors may be signalled during arithmetic: 


Divide exception This exception will be signalled if division by zero was attempted, 
or if the integer result of an integer divide or remainder operation had too many 
digits. 

Overflow/Underflow exception This exception will be signalled if the exponential 
part of a result (from an operation that is not an attempt to divide by zero) would 
exceed the range that can be handled by the language processor, when the result is 
formatted according to the current settings of numeric digitsand numeric form. 
The language defines a minimum capability for the exponential part, namely ex- 
ponents whose absolute value is at least as large as the largest number that can be 
expressed as an exact integer in default precision. Thus, since the default precision is 
nine, implementations must support exponents in the range -999999999 through 
999999999. 

Insufficient storage Storage is needed for calculations and intermediate results, and 
on occasion an arithmetic operation may fail due to lack of storage. ‘This is consid- 
ered an operating environment error as usual, rather than an arithmetical excep- 
tion. 


In the reference implementation, the exceptions and error types used for these three cases are 
DivideException, ExponentOverflowException, and OutOfMemoryError, respectively. 
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Binary values and operations 


By default, arithmetic and string operations in NetRExx are carried out using the 
NetRExx string class, RExx, which offers the robust set of operators described in Ex- 
pressions and operators (see page 47). 


NetRexx implementations, however, may also provide primitive datatypes, as described 
in Types and Classes (see page 27). These primitive types are used for compact storage 
of numbers and for fast binary arithmetic, features which are built-in to the hardware of 
most computers. 


To make use of binary arithmetic, a class is declared to be a binary class (see page 
by using the binary keyword on the class instruction. In such a class, literal strings 
and numeric symbols are assigned native string or primitive types, rather than NetRExx 
types, where appropriate, and native binary operations are used to implement operators 
where possible, as detailed below. Implementations may also provide a keyword on the 
opti ee page instruction that indicates that all classes in a program are binary 
classes. 


Alternatively, individual methods within a class may be declared to be a binary method 
(see page 96) by using the binary keyword on the method instruction. 


Alternatively, individual do groups within a method may be declared to be a do binary 
group (see page {73)) by using the binary keyword on the do instruction. 


Binary classes and methods should be used with care. Although binary arithmetic can 
have a considerable performance advantage over arithmetic that is not implemented in 
hardware, it can give incorrect or unexpected results. In particular, whole numbers (in- 
tegers) are often held in fixed-sized data areas (of 8, 16, 32, or 64 bits), and overflowing 
the data area during a calculation can result in a positive number becoming negative 
and vice versa. Similarly, binary numbers that are not whole numbers (floating-point 
numbers) cannot exactly represent common numbers in the decimal system (0.1, 0.2, 
etc.), and hence can give unexpected results. 


43.1 Operations in binary classes and methods 
In a binary class or method, the following (and only the following) rules differ from the 
usual rules: 


Dyadic operations in expressions Ifthe operands of a dyadic operator both have prim- 
itive numeric types @ then binary operations are carried out. The type of the result 





71 In the reference implementation, options binary is used. 
72 In the reference implementation, boolean is considered to be a numeric type (having the values 0 or 1) but char is not. Characters, 


165 


3.04 


is implementation defined, and is typically the type of the more precise of the two 
operands, or of some minimum precision. 2 Arithmetic operations follow the usual 
rules of binary arithmetic, as defined for the underlying environment of the imple- 
mentation. 

Note that NetRexx provides both divide and integer divide operators; in a binary 
class or method, the divide operator (”/”) converts its operands to floating-point 
types and returns a floating-point result, whereas the integer divide operator (”%”) 
converts its operands to integer types and returns an integer result. The remainder 
operator must accept both integer and floating-point types. 

Logical operations (and, or, and exclusive or) apply to all the bits of the operands, 
and are not permitted on floating-point types. 


Prefix operations in expressions If the operand of a prefix operator has a primitive nu- 
meric type, then the type of the result is the type of the operand, subject to the same 
minimum as dyadic operations. Prefix plus and minus follow the rules of dyadic op- 
erators (because they are defined as being zero plus or minus the operand) with the 
additional rule that if acting on a literal number (a constant in the program) then 
the result is also considered to be a literal constant. Logical not (prefix ”\”) does not 
apply to all the bits of its operand; instead, it changes a 0 to 1 and vice versa. 


Assignments In assignments where the value being assigned is the result of an expres- 
sion which comprises a string or number literal constant, the type of the result is 
defined as follows: 

1. Strings are given the native string type, even for a single-character literal. 4 
2. Numbers are given the smallest possible primitive numeric type that will con- 
tain the literal without loss of information (or minimal loss of information 
for numbers with decimal or exponential parts). If this is smaller than the 
implementation-defined minimum precision used for the result of adding the 
literal to 0, then the type of that minimum precision is used. 
If the constant is an integer, and no primitive integer binary type has sufh- 
cient precision to hold the number without loss of information, then the num- 
ber is treated as a literal string (that is, as though it were enclosed in quotes). 
NetRexx arithmetic would then be used if it were involved in an arithmetic 
operation. 
These rules can apply in assignment instructions, the initial assignment to the con- 
trol variable in the loop instruction, or the assignment of a default value to the 
argument of a method; the result type may define the type of the variable (if new, 
or a method argument). 


Control variables in loops In the loop instruction, if the control variable has a prim- 
itive integer type, and the increment (by value) has a primitive integer type, then 
binary arithmetic will be used for stepping the control variable, following the rules 
for binary arithmetic in expressions described above. 

Similarly, ifthe control variable has a primitive integer type, and the end (to) value 
has a primitive integer type, then binary arithmetic will be used for the comparison 
that tests for loop termination. 





and strings or arrays of characters, always use the rules defined for NetREXxx strings. 
3 In the reference implementation, the minimum precision is 32 bits, so an int is returned for results that would otherwise be byte or 
short. If both operands are boolean, however, and the operation is a logical operation, then the type of the result is boolean. 
74 In the reference implementation, this type is java.lang.String. 
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Numeric instruction The numeric instruction does not affect binary operations. It has 
the usual effects on operations carried out using NetRExx arithmetic. 


Note: At all times (whether in binary classes, binary methods, or anywhere else) imple- 
mentations may use primitive types and operations, and techniques such as late binding 
of types, as an optimization providing that the results obtained are identical to those 
defined in this language definition. 


43.2 Binary constructors 


NetReExx provides special constructors for implementation-defined primitive types that 
allow bit-wise construction of primitives. These binary constructors are especially useful 
for manipulating the binary encodings of individual characters. 


The binary constructors follow the same syntax as other constructors, with the name 
being that of a primitive type. All binary constructors take one argument, which must 
have a primitive type. 


The bits of the value of the argument are extended or truncated on the left to the same 
length as the bits required for the type of the constructor (following the usual binary 
rules of sign extension if the argument type is a signed numeric type), and a value with 
the type of the constructor is then constructed directly from those bits and returned. 


Example: This example illustrates types from the reference implementation, with 32-bit 
signed integers of type int and 16-bit Unicode characters of type char. 


i=int 77 -- i is now the integer 77 
c=char(i) -- c is now the character ’M’ 
j=int(c) -- j is now the integer 77 


Note that the conversion 
j=int c 


would have failed, as ”M” is not a number. 
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Exceptions 


Exceptional conditions, including errors, in NetRExx are handled bya mechanism called 
Exceptions. When an exceptional condition occurs, a signal takes place which may op- 
tionally be caught by an enclosing control construct, as detailed below. 


An exception can be signalled by: 


1. the program’s environment, when some processing error occurs (such as running 
out of memory, or a problem discovered when reading or writing a file) 


2. a method called by a NetRExx program (if, for example, it is passed incorrect ar- 
guments) 


3. the signal instruction (see page 123) . 


In all cases, the signal is handled in exactly the same way. First, execution of the cur- 
rent clause ceases; no further operations within the clause will be carried out. Next, an 
object that represents the exception is constructed. The type of the exception object is 
implementation-dependent, as described for the signal instruction (see page , and 
defines the type of the exception. The object constructed usually contains information 
about the Exception (such as a descriptive string). 


Once the object has been constructed, all active do groups, loop loops, if constructs, 
and select constructs in the active method are unwound’, starting with the innermost, 
until the exception is caught by a control construct that specifies a suitable catch clause 
(see below) for handling the exception. 


This unwinding takes place as follows: 


1. No further clauses within the body of the construct will be executed (in this respect, 
the signal acts like a leave for the construct). 


2. Ifa catch clause specifies a type to which the exception object can be assigned (that 
is, it matches or is a superclass of the type of exception object), then the instruction- 
list following that clause is executed, and the exception is considered to be handled 
(no further control constructs will be unwound). If more than one catch clause 
specifies a suitable type, the first is used. 


3. The instructionlist following the finally clause for the construct, if any, is executed. 


4. The end clause is executed, hence completing execution of the construct. (The only 
effect of this is that it is seen when tracing.) 


5. Ifthe exception was handled, then execution resumes as though the construct com- 
pleted normally. If it was not handled, then the process is repeated for any enclosing 
constructs. 





75 This is the only case in which an expression will not be wholly evaluated, for example. 
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If the exception is not caught by any of the control constructs enclosing the original point 
of the exception signal, then the current active method is terminated, without returning 
any data, and the exception is then signalled at the point where the method was invoked 
(that is, in the caller). 


The process of unwinding control constructs and terminating the method is then re- 
peated in each calling method until the exception is caught or the initial program invo- 
cation method (the main method) is terminated, in which case the program ends and the 
environment receives the signal (it would usually then display diagnostic information). 


44.1 Syntax and example 


The constructs that may be used to handle (catch) an exception are do groups, loop 
loops, and select constructs. Specifically, as shown in the syntax diagrams (q.v.), where 
the end clause can appear in these constructs, zero or more catch clauses can be used to 
define exception handlers, followed by zero or one finally clauses that describe “clean- 
up” code for the construct. The whole construct continues to be ended by an end clause. 


The syntax of a catch clause is shown in the syntax diagrams. It always specifies an ex- 
ception type, which may be qualified. It may optionally specify a symbol, vare, which 
is followed by an equals sign. This indicates that when the exception is caught then the 
object representing the exception will be assigned to the variable vare. If new, the type 
of the variable will be exception. Here is an example of a program that handles some of 
the exceptions signalled by methods in the RExx class; the trace results instruction 
is included to show the flow of execution: 


trace results 
do -- could be LOOP i=1 to 10, etc. 
say l/arg 
catch DivideException 
say ’Divide exception’ 
catch ex=NumberFormatException 
/* ?ex’ is assigned the exception object */ 
say ’Bad number for division:’ ex.getMessage 
finally 
say ’Done!’ 
end 


In this example, if the argument passed to the program (and hence placed in arg) is a 
valid number, then its inverse is displayed. Ifthe argument is 0, then ”Divide exception” 
would be displayed. If the argument were an invalid number, the message describing the 
bad number would be displayed. For any other exception (such as an ExponentOver- 
flowException), the program would end and the environment would normally report 
the exception. 


In all cases, the message "Done!” would be displayed; this would be true even if the 
body of the do construct executed a return, leave, or iterate instruction. Only an exit 
instruction (see page {/5)) would cause immediate termination of the construct (and the 
program). 
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Note: The finally keyword, like otherwise in the select construct, implies a semi- 
colon after it, so the last say instruction in the example could have appeared on the 
same line as the finally without an intervening semicolon. 


44.2 Exceptions after catch and finally clauses 


If an exception is signalled in the instructionlist following a catch or finally clause, then 
the current exception is considered handled, the instructionlist is terminated, and the 
new exception is signalled. It will not be caught by catch clauses in the current construct. 
If it occurs in the instructionlist following a catch clause, then any finally instructions 
will be executed, as usual. 


Similarly, executing a return or exit instruction within either of the instructionlists 
completes the handling of any pending signal. 


44.3 Checked exceptions 


NetRexx implementations may define certain exceptions as checked exceptions. These 
are exceptions that the implementation considers it useful to check; the checked ex- 
ceptions that each method may signal are recorded. Within do groups, loop loops, and 
select constructs, for example, it is then possible to report if a catch clause tries to 
catch a checked exception that is not signalled within the body of the construct. 


Checked exceptions that are signalled within a method (by a signal instruction or 
a method invocation) but not caught by a catch clause in the method are automati- 
cally added to the signals list for a method. Implementations that support checked 
exceptions are encouraged to provide options that list the uncaught checked exceptions 
for methods or enforce the explicit inclusion of some or all checked exceptions in the 
signals list on the method instruction. 


In the reference implementation, all exceptions are checked except those that are subclasses 
of java.lang.RuntimeException or java.lang.Error. These latter are considered so ubiq- 
uitous that almost all methods would signal them. 


Expressions assigned as the initial values of properties must not invoke methods that may 
signal checked exceptions. 


The strictsignal option on the options instruction may be used to enforce the inclusion 
of all uncaught checked exceptions in methods’ signals lists; this may be used to assure 
that any uncaught checked exceptions are intentional. 
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Thread Pool Support 


Support for thread pooling is built into the NetRExx language. 


rtp=RexxTaskPool(sizeynumber) size is the number of parallel threads desired - de- 
fault is the current number of available processors number is the number of the 
threadpool if using multiple pools - default is pool number 0 

rtp.start(runtask) runtask needs to be a class that implements the runnable interface 

rtp.start(maintask,mainparm) maintask is a NetRexx Java class with a standard *main” 
method mainparm is a string parm to pass to the main method at startup 

rtp.start(’taskname’;mainparm) taskname is a string identifying a Java class with a 
standard main method mainparm is a string parm to pass to the main method at 
startup 

rtp.waituntildone Blocks until all threads in the pool are finished 

rtp.waitforallpools Blocks until all threads in all task pools are complete 


45.1 Examples 


Listing 45.1: ThreadPool example 


RexxTaskPool(3,1).start(Test(7)).start(Test(8)).start("TestMain","9").start(" 
enviroscan") 
RexxTaskPool(9).start(Test(1)).start(Test(2)).start(TestMain("3") ,"3").start( 
enviroscan.class) 
RexxTaskPool().start(Test(4)).start(Test(5)).start(TestMain("6") ,"6") .waituntildone 
RexxTaskPool().start(Test(4)).start(Test(5)).start(TestMain("6") ,"6") .waitforallpools 





76the start method returns the RexxTaskPool instance it is called on so that multiple calls can be stacked. Due to reflection use 
when starting *main” methods that call format cannot be interpreted - runnables interpret ok 
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Structured Lists Interface 


A Structured List class is used to create objects which can contain structured or string 
encoded lists with associated methods for easy access. A Structured List class is a sub- 
class of the native NetRexx ”Rexx” class data type which implements the StructuredList 
interface as described below and can be used in many cases as a normal NetRexx data 
item. Assuming a class named "AStructuredList” is available to support structured lists: 


- A StructuredList class should have a constructor that sets the encoded list value 


This creates an unexamined (unstructured) list object. The object is an object of type 
Rexx with additional methods for processing lists. You must pass a Ruleset to the list 
object (see the *buildlist” method below) in order to obtain a structured version of the 
list object which can be accessed with list methods. Note that due to the immutability 
rule for base Rexx object values, all methods which alter the content of a structured list 
return a new structured list object. This rule also means that if a list is altered by a Java 
List view, the new structured list object must be obtained from the ’currentlist” property 
of the Java List view. 


Structured List formats knows to NetRExx include 


¢ WORDLIST 
« DSV 

° CSV 

- TSV 

° XML 

¢ JSON 

« PYTHON 


46.1 Essential List Processing Methods 


This section lists the methods provided by the StructuredList class. 


buildlist(ruleset) Returns a structured list form of the encoded list contained in the 
object's string value after examination with the provided ruleset. 

join(anotherStructuredList) Returns a structured list containing the elements of the 
structured list with the elements from another structured list appended to it. 

islist Returns 1 if the item is a structured list, otherwise returns 0. If a structured list is 
empty, index “elements” will have a 0 value. 

elementcount Returns the count of elements in a structured list. 

getelement(index) Returns the element at the specified location in a structured list. 
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getJavaList Returns a Java List interface view of the structured list. 
index(element,start) Returns the numeric index of the first occurence of the given el- 
ement in the list with index equal to or higher than start or 0 if not found. 


insertelement(index, element) Adds an element to a list at the specified location. Re- 
turns modified list. 


replaceanelement(index, element) Replaces an element of a list at the specified loca- 
tion. Returns modified list. 


deleteanelement(index) Removes an element from a list at the specified location. Re- 
turns modified list. 


sublist(fromIndex,toIndex) Creates a list which is a subset of the list containing the 
elements starting at the from index and ending at the to index. 


46.2 Convenience Methods 


append(element) Adds an element to the end of a list. Returns modified list. 
head Returns the first element in a list. 

tail Returns a list containing all elements except the first in a list. 
count(value) Returns a count of how many elements have the provided value. 


minval Returns the lowest value in a list. This is a runtime error if not all list elements 
are numeric. 


maxval Returns the highest value in a list. This is a runtime error if not all list elements 
are numeric. 


sum Returns the sum of all list elements. This is a runtime error if not all list elements 
are numeric. 


reverselist Returns a structured list with the order of the elements reversed. 


flatlist Returns a structured list with only the list elements (all metadata is removed). 
Nested sublists are also flattened. 


46.3 NetRexx Structured List Format 


A structured list is an ordered sequence of items stored in a NetRexx native data object 
(class Rexx) along with "meta data” describing the list. Each element of the list can be 
accessed with a whole number ranging from 1 to n where n is the number of elements 
in the list. The string encoded (aka "serialized”) form of the string is the base value of 
the Rexx object. If an element of a list is itself a list (ie a nested list), then elements of the 
sublist can also be accessed by whole number indexes so that for example the 3rd element 
of the nested list which is the second element of the first list could be found at myList[2,3] 
where myList is the object containing the structured list. Note that although a structured 
list is a Rexx object, changing the list directly rather than through the StructuredList 
interface methods will cause loss of metadata and unpredictable results for further list 
access. 
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46.3.1 Accessing structured lists with NetRexx facilities 


Assuming myList is a Rexx object containing a structured list, then: 


myList[”elements” | 
Provides a count of the number of elements in a structured list. This is meaningless 
if the item is not actually in the structured list format (ie if islist returns 0). 
myList[n,m | 
A list element can be accessed by numeric index using NetRexx indexed variable 
syntax. If the element is also a list, sub-elements can be accessed using the multiple 
index syntax. 


Additional indexed values 


”rules” The rules used to structure this list (the rules are also a structured list). The 
following indexes must be prefixed with ”#” to use if they are whole numbers ac- 
cording to the NetRexx datatype BIF - this avoids conflict with list index numbers. 

elementname If an element has a name, using the name as an index will return the 
associated element value. 

element The element string will return the index of the first location of that element in 
the list. elementvalue If an element has a name the named value string will return 
the index of the first location of that value in the list. 


46.4 Structured List Ruleset Description 


A list ruleset specifies a set of delimiters and options and can be provided in one of four 
ways: 


1. A null ruleset (or the string “default”) signifies a default ruleset. Default rules are 
start/end delimiters ”(” and ”)”, a separator” ” (a blank), an escape character ” (dou- 
ble quote), and the option “escape is quoted string mode”. 

2. A string such as "CSV’, which is a well known list format name, selects a built- 
in ruleset. For example, a list in CSV format could be decoded like this: in- 
putlist=inputstring.getlist(’?CSV”). Formats known to a Structured List include 
”*WORDLIST’, "DSV’, "CSV”, °TSV”, ">XML*, "JSON”, >PYTHON”. 

3. A string which provides a human readable custom set of list rules that is itself a 
decomposable list according to the default ruleset. Rulesets contain two sections: 
delimiters and options which are specified as separate sublists as in the following 
example: 


*>delimiters(start(”<”) end(”>”) separator(”,”) meta(”/”) escape(”\\”) 
nameseparator(”=”) ) 
options (separators-must-follow-sublists ”adjacent separators reduce to one”)’ 


4. A ruleset string that is itself an encoded list according to a known ruleset can sim- 
ply be preparsed before use like in this example: 
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inputlist=inputstring.buildlist(rulesetstring.buildlist(”default”) ) 


46.4.1 Delimiters 


Any type of delimiter can be specified but the following (along with the ruleset options) 
define the structure of a list. Other delimiters can be provided and will be recognized and 
recorded as list elements when they occur which means they are “defacto” separators for 
the list elements. 


Start A delimiter which signals the start of a sublist. Example: start(””) 

End A delimiter which signals the end of a sublist. Example: End(””) 

Escape An escape character used to include delimiters in the list data elements. Exam- 
ple: escape(”||”) 

Separator A delimiter used to separate list elements. Example: Separator(’’) 

NameSeparator A delimiter used to associate element names with element values. Ex- 
ample: Namesep(”=” 








46.4.2 Options 


The following options are recognized (A ”0” in front of the option indicates a default 
value and a ”1” indicates an option which overrides the default value. The additional 
descriptions in parenthesis are not part of the option. Options can be specified as quoted 
text or with dashes substituted for spaces. Options can be abbreviated as long as they are 
unique. Options are not case-sensitive. 


option 1 0 = separators follow sublists 
1 = sublists are separators 
option 2 0 = adjacent separators reduce to one 
1 = produce empty elements for adjacent separators 
option 3 © = translate escape sequences 
1 = do not translate escape sequences 
option 4 0 = whitespace is translated to blank (TAB,FF,LF,CR,VT) 
1 = treat whitespace as text 
option 5 0 = escape is quoted string mode (ie ”text, delimiters or double escape like thi 
1 = single character escape (ie \x) 
option 6 0 = attribute names are implicit (ie fun(x,y) ) 
1 = explicit attribute names (ie with delimiter as in fun=(x,y) or 
fun: (x,y) ) 
option 7 0 = delimiters are implicit (do not record structural delimiters) 
1 = tokens are delimiters (save delimiters as separate elements) 
option 8 0 = keep leading and trailing whitespace 
1 = strip leading and trailing whitespace 
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47 





Methods for NetREXxx strings 


This section describes the set of methods defined for the NetRExx string class, REXx. 
These are called built-in methods, and include character manipulation, word manipula- 
tion, conversion, and arithmetic methods. 


Implementations will also provide other methods for the RExx class (for example, to 
implement the NetRExx operators or to provide constructors with primitive arguments), 
but these are not part of the NetRexx language. 71 


47.1 General notes on the built-in methods: 


1. All methods work ona NetRExx string of type REXx; this is referred to by the name 
string in the descriptions of the methods. For example, if the word method were 
invoked using the term: 


"Three word phrase”.word(2) 


then in the description of word the name string refers to the string * Three word 
phrase’, and the name n refers to the string ”2”. 


2. All method arguments are of type RExx and all methods return a string of type 
Rexx; if a number is returned, it will be formatted as though 0 had been added 
with no rounding. 

3. The first parenthesis in a method call must immediately follow the name of the 
method, with no space in between. 

4, The parentheses in a method call can be omitted if no arguments are required and 
the method call is part of a compound term (see page BQ) . 23 

5. A position in a string is the number of a character in the string, where the first 
character is at position 1, etc. 

6. Where arguments are optional, commas may only be included between arguments 
that are present (that is, trailing commas in argument lists are not permitted). 

7. A pad argument, if specified, must be exactly one character long. 

8. Ifa method has a sub-option selected by the first character ofa string, that character 
may be in upper or lowercase. 

9. Conversion between character encodings and decimal or hexadecimal is depen- 
dent on the machine representation (encoding) of characters and hence will return 
appropriately different results for Unicode, ASCII, EBCDIC, and other implemen- 
tations. 





77 Details of the methods provided in the reference implementation are included in Appendix C (see page[I99) . 
78 Unless an implementation-provided option to disallow parenthesis omission is in force. 
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47.2 The built-in methods 


abbrev(info [,length]) returns 1 if info is equal to the leading characters of string and 
info is not less than the minimum length, length; 0 is returned if either of these 
conditions is not met. length must be a non-negative whole number; the default is 
the length of info. Examples: 


>Print’ .abbrev(’Pri’) == 
>PRINT’ .abbrev(’Pri’) == 
’PRINT’ .abbrev(’PRI’,4) == 
’PRINT’ .abbrev(’PRY’) = == 
>PRINT’ .abbrev(’’) == 
>PRINT’ .abbrev(’’ ,1) == 


OrFOO O F 


Note: A null string will always match if a length of 0 (or the default) is used. This 
allows a default keyword to be selected automatically if desired. Example: 
say ’Enter option:’; option=ask 
select /*x keywordl is to be the default */ 
when ’keyword1’.abbrev(option) then ... 
when ’keyword2’.abbrev(option) then ... 


otherwise ... 
end 


abs() returns the absolute value of string, which must be a number. Any sign is removed 
from the number, and it is then formatted by adding zero with a digits setting that 
is either nine or, if greater, the number of digits in the mantissa of the number 
(excluding leading insignificant zeros). Scientific notation is used, if necessary. 


Examples: 

712.3’ .abs == 12.3 

> -@.307’.abs == 0.307 
?123.45E+16’.abs == 1.2345E+18 


?— 1234567.7654321’ .abs == 1234567.7654321 


3.02 b2d([n]) Binary to decimal. Converts string, a string of at least one binary (0 and/or 1) 
digits, to an equivalent string of decimal characters (a number), without rounding. 
The returned string will use digits, and will not include any blanks. If the number 
of binary digits in the string is not a multiple of four, then up to three ’0’ digits will 
be added on the left before conversion to make a total that is a multiple of four. If 
string is the null string, 0 is returned. If n is not specified, string is taken to be an 
unsigned number. 
Examples: 


701110’ .b2d == 14 

710000001’ .b2d == 129 
7111110000001’ .b2d == 3969 
?1111111110000001’.b2d == 65409 
?1100011011110000’ .b2d == 50928 


If n is specified, string is taken as a signed number expressed in n binary characters. 
If the most significant (left-most) bit is zero then the number is positive; otherwise 
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it is a negative number in twos-complement form. In both cases it is converted to a 
NetRexx number which may, therefore, be negative. If n is 0, 0 is always returned. 
If necessary, string is padded on the left with ’0’ characters (note, not “signex- 
tended”), or truncated on the left, to length n characters; (that is, as though 
string.right(n, ’0’) had been executed.) 


Examples: 

710000001’ .b2d(8) == -127 
710000001’ .b2d(16) == 129 
?1111000010000001’ .b2d(16) == -3967 
71111000010000001’ .b2d(12) == 129 
71111000010000001’.b2d(8) == -127 
?1111000010000001’.b2d(4) == 1 


?Q000000000110001’.b2d(0) == 


b2x() Binary to hexadecimal. Converts string, a string of at least one binary (0 and/or 1) 
digits, to an equivalent string of hexadecimal characters. The returned string will 
use uppercase Roman letters for the values A-F, and will not include any blanks. If 
the number of binary digits in the string is not a multiple of four, then up to three 
0’ digits will be added on the left before conversion to make a total that is a multiple 


of four. 

Examples: 

711000011’.b2x == ’C3? 
710111’ .b2x a ae 
7Q@101’ .b2x See 05? 
7101’ .b2x ==n5? 
?111110000’.b2x == ’1F0’ 


center(length [,pad]) or 


centre(length [,pad]) returns a string of length length with string centered in it, with 
pad characters added as necessary to make up the required length. length must 
be a non-negative whole number. The default pad character is blank. If the string 
is longer than length, it will be truncated at both ends to fit. If an odd number 
of characters are truncated or added, the right hand end loses or gains one more 
character than the left hand end. 


Examples: 

>ABC’.centre(7) == °’ ABC ”’ 

>ABC’.center(8,’-’) == °--ABC---’ 
>The blue sky’.centre(8) == ’e blue s’ 
>The blue sky’.center(7) == ’e blue ’ 


Note: This method may be called either centre or center, which avoids difficulties 
due to the difference between the British and American spellings. 
changestr(needle, new) returns a copy of string in which each occurrence of the needle 
string is replaced by the new string. Each unique (non-overlapping) occurrence of 
the needle string is changed, searching from left to right and starting from the first 
(leftmost) position in string. Only the original string is searched for the needle, and 
each character in string can only be included in one match of the needle. 
If the needle is the null string, the result is a copy of string, unchanged. 
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Examples: 


elephant’ .changestr(’e’,’X’) == ’XLXphant’ 
elephant’ .changestr(’ph’,’X’) == ’eleXant’ 
elephant’ .changestr(’ph’,’hph’) == ’elehphant’ 
elephant’ .changestr(’e’,’’) == ’Lphant’ 
elephant’ .changestr(’’,’!!’) == ’elephant’ 


The countstr method (see page can be used to count the number of changes 
that could be made to a string in this fashion. 

compare(target [,pad]) returns 0 if string and target are the same. If they are not, the 
returned number is positive and is the position of the first character that is not 
the same in both strings. If one string is shorter than the other, one or more pad 
characters are added on the right to make it the same length for the comparison. 
The default pad character is a blank. 
Examples: 


>abc’.compare(’abc’) == 
>abc’.compare(’ ak’) == 
ab ’.compare(’ab’) == 
?ab ’.compare(’ab’,’ ’) == 
?ab ’.compare(’ab’,’x’) == 


awnodeodn ® 


>ab-- ’.compare(’ab’,’-’) == 
copies(n) returns n directly concatenated copies of string. n must be positive or 0; if 0, 


the null string is returned. 
Examples: 


?abc’.copies(3) == ’abcabcabc’ 
?abc’.copies(@) == ’’ 
>? .copies(2) == °? 


copyindexed(sub) copies the collection of indexed sub-values (see page 61)) of sub into 
the collection associated with string, and returns the modified string. The resulting 
collection is the union of the two collections (that is, it contains the indexes and 
their values from both collections). If a given index exists in both collections then 
the sub-value of string for that index is replaced by the sub-value from sub. 
The non-indexed value of string is not affected. 
Example: Following the instructions: 
foo=’def’ 
foo[’a’]=1 
foo[’b’]=2 
bar=’ghi’ 
bar[*b?]="B° 
bar[’c’?]=’C’ 
merged=foo.copyIndexed (bar) 
then: 


24? 
7B? 
"°C? 
def’ 


merged[’a’ 


merged[’b’ 


] 
] 
merged[’c’] 
] 


merged[’d’ 
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countstr(needle) returns the count of non-overlapping occurrences of the needle string 
in string, searching from left to right and starting from the first (leftmost) position 


in string. 

If the needle is the null string, 0 is returned. 
Examples: 

?elephant’.countstr(’e’) == ’2’ 
?elephant’.countstr(’ph’) == 71’ 
?elephant’.countstr(’’) == °@? 


The changestr method (see page can be used to change occurrences of needle 
to some other string. 

c2d() Coded character to decimal. Converts the encoding of the character in string 
(which must be exactly one character) to its decimal representation. The returned 
string will be a non-negative number that represents the encoding of the character 
and will not include any sign, blanks, insignificant leading zeros, or decimal part. 


Examples: 

7M’?’.c2d == °77’ -- ASCII or Unicode 
?7’?.c2d == °247’ -- EBCDIC 

*\r’?.c2d == °13’ -- ASCII or Unicode 
*"\0’.c2d == ’0’ 


The c2x method (see page can be used to convert the encoding of a character 
to a hexadecimal representation. 

c2x() Coded character to hexadecimal. Converts the encoding of the character in string 
(which must be exactly one character) to its hexadecimal representation (unpacks). 
The returned string will use uppercase Roman letters for the values A-F, and will 
not include any blanks. Insignificant leading zeros are removed. 


Examples: 

?M’?.c2x == °4D’ -- ASCII or Unicode 
"7? .c2x == °F7’? -- EBCDIC 

*\r?.c2x == °D’ -- ASCII or Unicode 
»\0’?.c2x == ’0? 


The c2d method (see page can be used to convert the encoding of a character 
to a decimal number. 
datatype(option) returns 1 if string matches the description requested with the option, 

or 0 otherwise. If string is the null string, 0 is always returned. 

Only the first character of option is significant, and it may be in either uppercase or 

lowercase. The following option characters are recognized: 

A (Alphanumeric); returns 1 if string only contains characters from the ranges ”a- 
z, A-Z”, and 0-9”. 

B (Binary); returns 1 if string only contains the characters ”0” and/or ”1”. 

D (Digits); returns 1 if string only contains characters from the range ”0-9”. 

L (Lowercase); returns 1 if string only contains characters from the range ”a-z’. 

M (Mixed case); returns 1 if string only contains characters from the ranges ”a-z” 
and “A-Z”. 

N (Number); returns 1 if string is a syntactically valid NetRExx number that could 
be added to ’0’ without error, 
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S (Symbol); returns 1 if string only contains characters that are valid in non- 
numeric symbols (the alphanumeric characters and underscore), and does 
not start with a digit. Note that both uppercase and lowercase letters are per- 
mitted. 

U (Uppercase); returns 1 if string only contains characters from the range “A-Z”. 

W (Whole Number); returns 1 if string is a syntactically valid NetRExx number 
that can be added to ’0’ without error, and whose decimal part after that ad- 
dition, with no rounding, is zero. 

X (heXadecimal); returns 1 if string only contains characters from the ranges ”a-f”, 
"A-F’, and ”0-9”. 

Examples: 


7101’ .datatype(’B’) == 
712.3’ .datatype(’D’) == 
712.3’ .datatype(’N’) == 
712.3’ .datatype(’W’ ) == 
>LaArca’.datatype(’M’) == 
>? datatype(’M’ ) qm 
’Llanes’.datatype(’L’) == 
73 d’ .datatype(’s’) == 
>BCd3’ .datatype(’X’) == 
>BCgd3’.datatype(’X’) == 


FOO OF OF GO F 


[o) 


Note: The datatype method tests the meaning of the characters in a string, inde- 
pendent of the encoding of those characters. Extra letters and Extra digits cause 
datatype to return 0 except for the number tests ("N” and ”W”), which treat extra 
digits whose value is in the range 0-9 as though they were the corresponding Arabic 
numeral. 

delstr(n [,length]) returns a copy of string with the sub-string of string that begins at the 
nth character, and is of length length characters, deleted. If length is not specified, 
or is greater than the number of characters from n to the end of the string, the rest 
of the string is deleted (including the nth character). length must be a non-negative 
whole number, and n must be a positive whole number. If is greater than the 
length of string, the string is returned unchanged. 


Examples: 

>abcd’.delstr(3) == ’ab’ 
>abcde’.delstr(3,2) == ’abe’ 
>abcde’ .delstr(6) == ’abcde’ 


delword(n [,length )] 

returns a copy of string with the sub-string of string that starts at the nth word, and 
is of length length blank-delimited words, deleted. If length is not specified, or is 
greater than number of remaining words in the string, it defaults to be the remain- 
ing words in the string (including the nth word). length must be a non-negative 
whole number, and n must be a positive whole number. If is greater than the 
number of words in string, the string is returned unchanged. The string deleted 
includes any blanks following the final word involved, but none of the blanks pre- 
ceding the first word involved. 

Examples: 
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’Now is the time’.delword(2,2) == ’Now time’ 
>Now is the time ’.delword(3) == ’Now is ’ 
>Now time’.delword(5) == ’Now time’ 


d2b([n]) Decimal to binary. Returns a string of binary characters of length as needed 3.02 
or of length n, which is the binary representation of the decimal number. The re- 
turned string will use 0 and 1 characters for binary values. string must be a whole 
number, and must be non-negative unless n is specified, or an error will result. If n 
is not specified, the length of the result returned is such that there are no leading 0 
characters, unless string was equal to 0 (in which case ’0’ is returned). 

If n is specified it is the length of the final result in characters; that is, after conver- 
sion the input string will be sign-extended to the required length (negative num- 
bers are converted assuming twos-complement form). If the number is too big to 
fit into n characters, it will be truncated on the left. n must be a nonnegative whole 
number. 

Examples: 


?0’.d2b == 

79’ .d2b == 1001 

719’ .d2b == 10011 
?129’.d2b == 10000001 


299% .d2b(1). == 
7129’.d2b(8) == 10000001 
7127’ .d2b(12) == 000001111111 


7129’ .d2b(16) == 0000000010000001 
7257’ .d2b(8) == 00000001 
?-127’.d2b(8) == 10000001 

7-127’ .d2b(16) == 1111111110000001 
712’.d2b(0) == 


d2c() Decimal to coded character. Converts the string (a NetRExx number) to a single 
character, where the number is used as the encoding of the character. 
string must be a non-negative whole number. An error results if the encoding de- 
scribed does not produce a valid character for the implementation (for example, if 
it has more significant bits than the implementation’s encoding for characters). 


Examples: 
?77’.d2c == ’M’ -- ASCII or Unicode 
>+77’?.d2c == ’M’ -- ASCII or Unicode 
247’ .d2c == °7’ -- EBCDIC 
°0’ .d2c == ’\ 0’ 

d2x([n )] 


Decimal to hexadecimal. Returns a string of hexadecimal characters of length as 
needed or of length n, which is the hexadecimal (unpacked) representation of the 
decimal number. ‘The returned string will use uppercase Roman letters for the val- 
ues A-F, and will not include any blanks. string must be a whole number, and must 
be non-negative unless n is specified, or an error will result. If n is not specified, the 
length of the result returned is such that there are no leading 0 characters, unless 
string was equal to 0 (in which case ’0’ is returned). 
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If n is specified it is the length of the final result in characters; that is, after conver- 
sion the input string will be sign-extended to the required length (negative num- 
bers are converted assuming twos-complement form). If the number is too big to 
fit into n characters, it will be truncated on the left. m must be a non-negative whole 


number. 

Examples: 

79? .d2x == 79’ 
7129’ .d2x == °81’ 
7129’.d2x(1) == °1? 
7129’ .d2x(2) == ’81? 
7127?.d2x(3) == °O7F? 
7129’ .d2x(4) == °0081? 
°257’.d2x(2) == ’O1? 
7-127’ .d2x(2) == 781? 
7-127’ .d2x(4) == °FF81? 
712’.d2x(0) ==? 


returns 1 if index names a sub-value (see page 61) of string that has explicitly been 
assigned a value, or 0 otherwise. 
Example: Following the instructions: 
exists(index) vowel=0 
vowel[’a’ ]=1 
voweL[’b’]=1 


vowel[’b’]=null -- drops previous assignment 
then: 

vowel.exists(’a’) == ’1’ 

vowel.exists(’b’) == ’0’ 

vowel.exists(’c’) == ’Q’ 


format([before [,after ])] 
formats (lays out) string, which must be a number. 
The number, string, is first formatted by adding zero with a digits setting that is 
either nine or, if greater, the number of digits in the mantissa of the number (ex- 
cluding leading insignificant zeros). Ifno arguments are given, the result is precisely 
that of this operation. 
The arguments before and after may be specified to control the number of characters 
to be used for the integer part and decimal part of the result respectively. If either 
of these is omitted (with no arguments specified to its right), or is null, the number 
of characters used will be as many as are needed for that part. 
before must be a positive number; if it is larger than is needed to contain the integer 
part, that part is padded on the left with blanks to the requested length. If before is 
not large enough to contain the integer part of the number (including the sign, for 
negative numbers), an error results. 
after must be a non-negative number; if it is not the same size as the decimal part of 
the number, the number will be rounded (or extended with zeros) to fit. Specifying 
0 for after will cause the number to be rounded to an integer (that is, it will have no 
decimal part or decimal point). 
Examples: 
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> - 12.73’.format == °’-12.73’ 


70.000’ .format == °Q’ 

°3’. format (4) ==? 3? 
°1.73’. format (4,0) ==? 2? 
°1.73’. format (4,3) ==? 1.730’ 
°>-.76’. format (4,1) == ° -0.8’ 
?3.03’. format (4) ==? 3.03’ 
> — 12.73’.format(null,4) == ’-12.7300’ 


Further arguments may be passed to the format method to control the use of ex- 
ponential notation. The full syntax of the method is then: 

format ([before[,after[,explaces[,exdigits[,exform]]]]]) The first two 
arguments are as already described. The other three (explaces, exdigits, and ex- 
form) control the exponent part of the result. The default for any of the arguments 
may be selected by omitting them (if there are no arguments to be specified to their 
right) or by using the value null. 

explaces must be a positive number; it sets the number of places (digits after the 
sign of the exponent) to be used for any exponent part, the default being to use as 
many as are needed. If explaces is specified and is not large enough to contain the 
exponent, an error results. If explaces is specified and the exponent will be 0, then 
explaces+2 blanks are supplied for the exponent part of the result. 

exdigits sets the trigger point for use of exponential notation. If, after the first for- 
matting, the number of places needed before the decimal point exceeds exdigits, 
or if the absolute value of the result is less than 0.000001, then exponential form 
will be used, provided that exdigits was specified. When exdigits is not specified, 
exponential notation will never be used. The current setting of numeric digits 
may be used for exdigits by specifying the special word digits (see page If 
0 is specified for exdigits, exponential notation is always used unless the exponent 
would be 0. 

exform sets the form for exponential notation (if needed). exform may be either 
Scientific’ (the default) or Engineering’. Only the first character of exform is sig- 
nificant and it may be in uppercase or in lowercase. The current setting of numeric 
form may be used by specifying the special word form (see page . If engineer- 
ing form is in effect, up to three digits (plus sign) may be needed for the integer 
part of the result (before). 


Examples: 

?12345.73’.format(null,null,2,2) == ’1.234573E+04’ 
?12345.73’.format(null,3,null,0) == ’1.235E+4’ 
?1.234573’.format(null,3,null,0) == °1.235”’ 
7123.45’. format(null,3,2,0) == ?1.235E+02’ 
?1234.5’.format(null,3,2,0,’e’) == ’1.235E+03’ 
71.2345’. format (null,3,2,0) == 71.235 ? 
?12345.73’.format(null,null,3,6) == ’12345.73 : 
?12345e+5’ . format (null, 3) == °1234500000.000’ 


Implementation minimum: If exponents are supported in an implementation, 
then they must be supported for exponents whose absolute value is at least as large 
as the largest number that can be expressed as an exact integer in default precision, 
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i.e., 999999999. Therefore, values for explaces of up to 9 should also be supported. 
insert(new [,n [,length [,pad]]]) inserts the string new, padded or truncated to length 
length, into a copy of the target string after the nth character; the string with any 
inserts is returned. length and n must be a non-negative whole numbers. If n is 
greater than the length of the target string, padding is added before the new string 
also. The default value for n is 0, which means insert before the beginning of the 
string. The default value for length is the length of new. The default pad character 


is a blank. 

Examples: 

abc’. insert(’123’) == ?123abc’ 
?abcdef’.insert(’ ’,3) == ’abc def’ 
?abc’.insert(’123’ ,5,6) == ’abc 123 2 
?abc’.insert(’?123’,5,6,’+’?) == ’abc++123+++’ 
?abc’.insert(’123’,0,5,’-’) == ’123--abc’ 


lastpos(needle [,start]) returns the position of the last occurrence of the string needle in 
string (the ”haystack”), searching from right to left. If the string needle is not found, 
or is the null string, 0 is returned. By default the search starts at the last character of 
string and scans backwards. This may be overridden by specifying start, the point 
at which to start the backwards scan. start must be a positive whole number, and 
defaults to the value string.length if larger than that value or if not specified (with 
a minimum default value of one). 
Examples: 


?abc def ghi’.lastpos(’ ’) _ 
?abc def ghi’.lastpos(’ ’,7) == 
-abcdefghi’.lastpos(’ ”) == 
’abcdefghi’.lastpos(’cd’) == 
>? .lastpos(’?’) == 


Oo WwW eo hk Ow 


left(length [,pad]) returns a string of length length containing the left-most length char- 
acters of string. The string is padded with pad characters (or truncated) on the right 
as needed. The default pad character is a blank. length must be a non-negative whole 
number. This method is exactly equivalent to string.substr(1, length |, pad)}). 


Examples: 

abc d’.left(8) == ’abc d : 
abc d’.left(8,’.’) == ’abe d...’ 
?abc defg’.left(6) == ’abc de’ 


length() returns the number of characters in string. 
Examples: 
?abcdefgh’.length == 
>? ,length == 

lower([n [,length] )] 
returns a copy of string with any uppercase characters in the sub-string of string 
that begins at the nth character, and is of length length characters, replaced by their 
lowercase equivalent. 
n must be a positive whole number, and defaults to 1 (the first character in string). 
If n is greater than the length of string, the string is returned unchanged. 
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length must be a non-negative whole number. If length is not specified, or is greater 
than the number of characters from n to the end of the string, the rest of the string 
(including the nth character) is assumed. 


Examples: 

>SumA’ . Lower == ’suma’ 
>SumA’ . Lower (2) == ’Suma’ 
>SUMB’. Lower(1,1) == ’SUMB’ 
>SUMB’.Lower(2,2) == ’SumB’ 
>? . lower ad 


returns the larger of string and number, which must both be numbers. If they com- 
pare equal (that is, when subtracted, the result is 0), then string is selected for the 
result. 
The comparison is effected using a numerical comparison with a digits setting that 
is either nine or, if greater, the larger of the number of digits in the mantissas of the 
two numbers (excluding leading insignificant zeros). 
The selected result is formatted by adding zero to the selected number with a dig- 
its setting that is either nine or, if greater, the number of digits in the mantissa of 
the number (excluding leading insignificant zeros). Scientific notation is used, if 
necessary. 
Examples: 

max(number) 0.max (1) ==] 
>-1’ .max(1) ==1 
>+1’ .max(-1) ==1 
71.0’ .max(1.00) =='1.0’ 
71.00’ .max(1.0) =='1.00’ 
7123456700000’ .max (1234567E+5) == °123456700000’ 
?1234567E+5’ .max(’?123456700000’) == ’1.234567E+11’ 


min(number) returns the smaller of string and number, which must both be numbers. If 
they compare equal (that is, when subtracted, the result is 0), then string is selected 
for the result. 
The comparison is effected using a numerical comparison with a digits setting that 
is either nine or, if greater, the larger of the number of digits in the mantissas of the 
two numbers (excluding leading insignificant zeros). 
The selected result is formatted by adding zero to the selected number with a dig- 
its setting that is either nine or, if greater, the number of digits in the mantissa of 
the number (excluding leading insignificant zeros). Scientific notation is used, if 
necessary. 
Examples: 


@.min(1) == 

>-1’ .min(1) ==’-]? 

>+1’ .min(-1) ==’-]? 

71.0’ .min(1.00) =='1.0’ 

71.00’ .min(1.0) ==’1.00’ 

? 123456700000’ .min(1234567E+5) == °123456700000’ 
?1234567E+5’ .min(’?123456700000’) == ’?1.234567E+11’ 
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overlay(new [,n [,length [,pad]]]) overlays the string new, padded or truncated to 
length length, onto a copy of the target string starting at the nth character; the 
string with any overlays is returned. Overlays may extend beyond the end of the 
original string. If length is specified it must be a non-negative whole number. If n is 
greater than the length of the target string, padding is added before the new string 
also. The default pad character is a blank, and the default value for n is 1. n must 
be greater than 0. The default value for length is the length of new. 


Examples: 

>abcdef’.overlay(’ ’,3) == ’ab def’ 
>abcdef’ .overlay(’.’,3,2) == ’ab. ef?’ 
>abcd’ .overlay(’qq’) == ’qqcd’ 
?abcd’ .overlay(’qq’ ,4) == ’abcqq’ 
?abc’ .overlay(’123’ ,5,6,’+’) == ’abc+123+++’ 


pos(needle [,start]) returns the position of the string needle, in string (the "haystack”), 
searching from left to right. If the string needle is not found, or is the null string, 0 is 
returned. By default the search starts at the first character of string (that is, start has 
the value 1). This may be overridden by specifying start (which must be a positive 
whole number), the point at which to start the search; if start is greater than the 
length of string then 0 is returned. Examples: 


>Saturday’.pos(’day’) == 
?abc def ghi’.pos(’x’) == 
?abc def ghi’.pos(’ ’) == 4 
?abc def ghi’.pos(’ ’,5) == 


reverse() returns a copy of string, swapped end for end. 


Examples: 

7>ABc.’. reverse == ’?,cBA’ 

*>XYZ ’?. reverse == ° ZYX? 
’Tranquility’.reverse == ’ytiliuqnarT’ 


right(length [,pad]) returns a string of length Jength containing the right-most length 
characters of string - that is, padded with pad characters (or truncated) on the left as 
needed. The default pad character is a blank. Jength must be a non-negative whole 


number. 

Examples: 

abc) 6d’. right(8) ==’ abc d?’ 
?abc def’. right(5) == ’c def’ 
712’ .right(5,’0’) == ’00012’ 


sequence(final) returns a string of all characters, in ascending order of encoding, be- 
tween and including the character in string and the character in final. string and 
final must be single characters; if string is greater than final, an error is reported. 
Examples: 
?a’?.sequence(’f’) == ’abcdef’ 
? 
0’ .sequence(’ 
x03’) aoe 
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x00 

x01 

x02 

x03’ 

? 
ufffe’.sequence(’ 
uffff’?) == ’ 
ufffe 

uf fff’ 


sign() returns a number that indicates the sign of string, which must be a number. string 
is first formatted, just as though the operation ’string+0” had been carried out with 
sufficient digits to avoid rounding. If the number then starts with ’-’ then ’-1’ is 
returned; if it is 0’ then 0’ is returned; and otherwise ’1’ is returned. 


Examples: 

?12.3’.sign == 1 
?0.0’.sign == 

> -0.307’.sign == -1 


space([n [,pad]]) returns a copy of string with the blank-delimited words in string for- 
matted with n (and only n) pad characters between each word. n must be a non- 
negative whole number. If 1 is 0, all blanks are removed. Leading and trailing blanks 
are always removed. The default for n is 1, and the default pad character is a blank. 


Examples: 

?abc «def ’.space == ’abc def’ 

> abc def ’.space(3) == ’abc def’ 
?abc «def ’.space(1) == ’abc def’ 
?abc «def ’.space(Q) == ’abcdef’ 
?abc «def ’.space(2,’+’) == ’abctt+def’ 


strip([option [,char]] )] returns a copy of string with Leading, Trailing, or Both leading 
and trailing characters removed, when the first character of option is L, T, or B 
respectively (these may be given in either uppercase or lowercase). The default is B. 
The second argument, char, specifies the character to be removed, with the default 
being a blank. If given, char must be exactly one character long. 


Examples: 

> abc ’.strip == ’ab c’ 

> abc ’.strip(’L’) == ’abc °’ 
> abc ’.strip(’t’) == ’? ab c’ 
712.70000’.strip(’t’,@) == °12.7° 
79012.700’.strip(’b’,0) == ’12.7’ 


substr(n [,length [,pad]]) returns the sub-string of string that begins at the nth char- 
acter, and is of length length, padded with pad characters if necessary. n must be 
a positive whole number, and /ength must be a non-negative whole number. If n 
is greater than string.length, then only pad characters can be returned. If length is 
omitted it defaults to be the rest of the string (or 0 if n is greater than the length of 
the string). The default pad character is a blank. 
Examples: 
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>abc’.substr(2) == ’bc’ 


?abc’.substr (2,4) == ’bc ’” 
?abc’.substr (5,4) ==? 4 
?abc’.substr(2,6,’.’) == ’bc....’ 


?abc’.substr(5,6,’.’) == ’...... : 


Note: In some situations the positional (numeric) patterns of parsing templates are 
more convenient for selecting sub-strings, especially if more than one sub-string is 
to be extracted from a string. 

subword(n [,length]) returns the sub-string of string that starts at the nth word, and 
is up to length blank-delimited words long. n must be a positive whole number; 
if greater than the number of words in the string then the null string is returned. 
length must be a non-negative whole number. If length is omitted it defaults to be 
the remaining words in the string. The returned string will never have leading or 
trailing blanks, but will include all blanks between the selected words. 


Examples: 
’Now is the time’.subword(2,2) == ’is the’ 
’Now is the time’.subword(3) == ’the time’ 


’Now is the time’.subword(5) ==”? 


translate(tableo, tablei [,pad]) returns a copy of string with each character in string ei- 
ther unchanged or translated to another character. 
The translate method acts by searching the input translate table, tablei, for each 
character in string. If the character is found in tablei (the first, leftmost, occurrence 
being used if there are duplicates) then the corresponding character in the same 
position in the output translate table, tableo, is used in the result string; otherwise 
the original character found in string is used. The result string is always the same 
length as string. 
The translate tables may be of any length, including the null string. The output 
table, tableo, is padded with pad or truncated on the right as necessary to be the 
same length as tablei. The default pad is a blank. 


Examples: 

->abbc’.translate(’&’,’b’) == °a&&c’ 
>abcdef’.translate(’12’,’ec’) == ’ab2d1f’ 
>abcdef’.translate(’12’,’abcd’,’.’) == °12..ef’ 
74123’ .translate(’ abcd’ ,’1234’) == ’dabc’ 
74123’ .translate(’hods’ ,’1234’) == ’shod’ 


Note: The last two examples show how the translate method may be used to move 
around the characters in a string. In these examples, any 4-character string could 
be specified as the first argument and its last character would be moved to the be- 
ginning of the string. Similarly, the term: 


*>gh.ef.abcd’.translate(19970827, ’abcdefgh’ ) 

(which returns ”27.08.1997”) shows how a string (in this case perhaps a date) might 

be re-formatted and merged with other characters using the translate method. 
trunc([n]) returns the integer part of string, which must be a number, with n decimal 


places (digits after the decimal point). n must be a non-negative whole number, and 
defaults to zero. 
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The number string is formatted by adding zero with a digits setting that is either 
nine or, if greater, the number of digits in the mantissa of the number (excluding 
leading insignificant zeros). It is then truncated to n decimal places (or trailing 
zeros are added if needed to make up the specified length). If is 0 (the default) then 
an integer with no decimal point is returned. ‘The result will never be in exponential 


form. 

Examples: 

712.3’ .trunc == 12 
7127.09782’.trunc(3) == 127.097 
7127.1’ .trunc(3) == 127.100 
7127’ .trunc(2) == 127.00 
?0’?..trunc(2) == 0.00 


upper([n [,length]]) returns a copy of string with any lowercase characters in the sub- 
string of string that begins at the nth character, and is of length length characters, 
replaced by their uppercase equivalent. 
n must be a positive whole number, and defaults to 1 (the first character in string). 
If n is greater than the length of string, the string is returned unchanged. 
length must be a non-negative whole number. If length is not specified, or is greater 
than the number of characters from n to the end of the string, the rest of the string 
(including the nth character) is assumed. 


Examples: 

>Fou-Baa’ .upper == ’FOU-BAA’ 
>Mad Sheep’ .upper == ’MAD SHEEP’ 
’Mad sheep’ .upper (5) == ’?Mad SHEEP’ 
’Mad sheep’ .upper(5,1) == ’Mad Sheep’ 
’Mad sheep’ .upper(5,4) == ’Mad SHEEp’ 
>tinganon’.upper(1,1) == ’Tinganon’ 
>? upper Sauk? 


verify(reference [,option [,start]]) verifies that string is composed only of characters 
from reference, by returning the position of the first character in string that is not 
also in reference. If all the characters were found in reference, 0 is returned. The 
option may be either Nomatcl’ (the default) or Match’. Only the first character 
of option is significant and it may be in uppercase or in lowercase. If ’Match’ is 
specified, the position of the first character in string that is in reference is returned, 
or 0 is returned if none of the characters were found. The default for start is 1 (that 
is, the search starts at the first character of string). This can be overridden by giv- 
ing a different start point, which must be positive. If string is the null string, the 
method returns 0, regardless of the value of the option. Similarly if start is greater 
than string.length, 0 is returned. If reference is the null string, then the returned 
value is the same as the value used for start, unless Match’ is specified as the op- 
tion, in which case 0 is returned. 
Examples: 


7123’ .veri fy(’ 1234567890’ ) == 
?1Z3’ .verify(’ 1234567890’ ) = 
ABT’ . veri fy(’ 1234567890’ ,’M’) == 
7 1P3Q4’ . veri fy(’1234567890’,’N’,3) == 4 
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>ABCDE’ .verify(’’,’n’,3) == 
> AB3CD5’ .verify(’?1234567890’,’m’,4) == 6 


word(n) returns the nth blank-delimited word in string. n must be positive. If there are 
fewer than n words in string, the null string is returned. This method is exactly 
equivalent to string.subword(n,1). 
Examples: 


>Now is the time’.word(3) == ’the’ 
>Now is the time’.word(5) == ’’ 


wordindex(n) returns the character position of the nth blank-delimited word in string. 
n must be positive. If there are fewer than n words in the string, 0 is returned. 
Examples: 
>Now is the time’ .wordindex(3) == 8 
’Now is the time’ .wordindex(6) == 


wordlength(n) returns the length of the nth blank-delimited word in string. n must be 
positive. If there are fewer than n words in the string, 0 is returned. 


Examples: 

’Now is the time’ .wordlength(2) == 2 
*>Now comes the time’.wordlength(2) == 5 
’Now is the time’ .wordlength(6) == 0 


wordpos(phrase [,start]) searches string for the first occurrence of the sequence of 
blank-delimited words phrase, and returns the word number of the first word of 
phrase in string. Multiple blanks between words in either phrase or string are treated 
as a single blank for the comparison, but otherwise the words must match exactly. 
Similarly, leading or trailing blanks on either string are ignored. If phrase is not 
found, or contains no words, 0 is returned. By default the search starts at the first 
word in string. This may be overridden by specifying start (which must be positive), 
the word at which to start the search. 
Examples: 


>now is the time’ .wordpos(’ the’) == 
>now is the time’ .wordpos(’ The’) == 
>now is the time’.wordpos(’is the’) == 
>now is the time’ .wordpos(’is the’) == 
>now is the time’.wordpos(’is time’) == 
>To be or not to be’.wordpos(’be’) == 
>To be or not to be’.wordpos(’be’ ,3) == 


DNNONN GO W 


words() returns the number of blank-delimited words in string. 
Examples: 
>Now is the time’.words == 4 
? 


> ,words == 
>? -words == 


x2b() Hexadecimal to binary. Converts string (a string of at least one hexadecimal char- 
acters) to an equivalent string of binary digits. Hexadecimal characters may be any 
decimal digit character (0-9) or any of the first six alphabetic characters (a-f), in 


194 


either lowercase or uppercase. string may be of any length; each hexadecimal char- 
acter with be converted to a string of four binary digits. The returned string will 
have a length that is a multiple of four, and will not include any blanks. 


Examples: 

°C3’.x2b == °11000011? 

7? on S211? 
?1C1’.x2b == °000111000001’ 


x2c() Hexadecimal to coded character. Converts the string (a string of hexadecimal 
characters) to a single character (packs). Hexadecimal characters may be any deci- 
mal digit character (0-9) or any of the first six alphabetic characters (a-f), in either 
lowercase or uppercase. 
string must contain at least one hexadecimal character; insignificant leading zeros 
are removed, and the string is then padded with leading zeros if necessary to make 
a sufficient number of hexadecimal digits to describe a character encoding for the 
implementation. 
An error results if the encoding described does not produce a valid character for 
the implementation (for example, if it has more significant bits than the implemen- 
tation’s encoding for characters). Examples: 


?Q004D’.x2c == ’M’ -- ASCII or Unicode 
>Ad’ .x2c == °’M’ -- ASCII or Unicode 
7A2’ .x2c == ’s’ -- EBCDIC 

70’ .x2c == ’\ 0’ 


The d2c method (see page {185)) can be used to convert a NetRExx number to the 
encoding of a character. 


x2d([n]) Hexadecimal to decimal. Converts the string (a string of hexadecimal char- 
acters) to a decimal number, without rounding. If string is the null string, 0 is re- 


turned. 

If n is not specified, string is taken to be an unsigned number. 
Examples: 

7@E’.x2d == 14 

?81’.x2d == 129 

?F81’ .x2d == 3969 

7>FF81’.x2d == 65409 

>c6fO’.x2d == 50928 


If n is specified, string is taken as a signed number expressed in n hexadecimal 
characters. If the most significant (left-most) bit is zero then the number is positive; 
otherwise it is a negative number in twos-complement form. In both cases it is 
converted to a NetRExx number which may, therefore, be negative. If n is 0, 0 is 
always returned. 

If necessary, string is padded on the left with ’0° characters (note, not "sign- 
extended”), or truncated on the left, to length n characters; (that is, as though 
string.right(n, ’0’) had been executed.) 


Examples: 
781? ,2d@) == 227 
781’,.x2d(4) == 129 
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?>FO81’.x2d(4) == -3967 

>FO81’.x2d(3) == 129 

?>FO81’.x2d(2) == -127 

?FO81’.x2d(1) == 1 

?Q031’.x2d(0) == 

The c2d method (see page {183]) can be used to convert a character to a decimal 
representation of its encoding. 
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Appendix A - A Sample NetRExx Program 


This appendix includes a short program, called qtime, which is an example of a ’real” 
NetRexx program. The programs included elsewhere in this book have been contrived 
to illustrate specific points. By contrast, qtime is a simple but useful tool that genuinely 
improves the human factors of computer systems. People frequently wish to know the 
time of day, and this program presents this information in a natural way. 


The style used for this example is the same as that used throughout the book, with all 
symbols except those describing classes being written in lower case. Other NetRExx pro- 
gramming styles are possible, of course; NetRExx syntax is designed to permit a wide 
variety of styles with a minimum of punctuation. 

The qtime program is a modification of one of the first RExx programs ever written 
(much of the program is identical). The main changes are: 


¢ Indexed variables (brackets notation) are used instead of RExx stems. 


¢ The word method from the RExx class is used instead of the word RExx built-in 
function. 


¢ The Java Date class is used to determine the current time. 


qtime.nrx - Query Time 


Listing 48.1: qtime.nrx 





/x QTIME. This program displays the time in real English. ,/ 
/x If "2?" is given as the first argument word then the ,/ 
/% program displays a description of itself. ,/ 


aaa ama la a ak i «/ 
pga esse anes First process any areument words ====-===-=-=-== gy 
parse arg parm . /x get the first argument word ,/ 
select 
when parm='?!' then tell /x say what we do ,/ 
when parm='' then nop /x% OK (no first argument) ,/ 
otherwise 


say 'The only valid argument to QTIME is "?". The word' 
say 'that you supplied ("'parm'") has been ignored.' 


tell /x usually helpful to describe the program ,/ 
end 
{4 =ss=s== Now Start processing in earnest <-<-<-<-<--<---- af 
/» Nearness phrases - using associative array lookup ,/ 
near='' /x% default ,/ 
near[Q]='' /x% exact ,/ 


near[1]=' just gone'; near[2]=' just after' /, after ,/ 
near[3]=' nearly'; near[4]=' almost' /, before ,/ 


/x Extract the hours, minutes, and seconds from the time. ,/ 
/x Use the Java Date class as Rexx.Date not yet implemented ,/ 
parse Date() .. . now. /y% time is fourth word ,/ 

parse now hour!':'min':'sec 
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29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 


45 
46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
56 
57 
58 
59 
60 
61 
62 
63 
64 
65 
66 
67 
68 
69 
70 
71 
72 
73 
74 
75 
76 
77 
78 
79 
80 
81 
82 
83 
84 
85 


if sec>29 then min=mint+1 /x round up minutes ,/ 


mod=min//5 /x where we are in 5 minute bracket ,/ 
out="It's"near [mod] /x start building the result ,/ 
if min>32 then hour=hour+1l /y, we are TO the hour... ,/ 


min=mint2 /, shift minutes to straddle a 5-minute point ,/ 


/»% Now special-case the result for Noon and Midnight hours ,/ 
if hour//12=0 & min//60<=4 then do 
if hour=12 then say out 'Noon.' 
else say out 'Midnight.' 


return /x we are finished here ,/ 
end 
min=min-(min//5) /»% find nearest 5 mins ,/ 
if hour>12 
then hour=hour-12 /x get rid of 24-hour clock ,/ 
else 


if hour=0 then hour=12 /, .. and allow for midnight ,/ 


/x Determine the phrase to use for each 5-minute segment ,/ 
select 

when min=0 then nop /y add “o'clock” later 5/ 

when min=60 then min=0 pee CIEEO 2. / 

when min= 5 then out=out 'five past! 

when min=10 then out=out 'ten past' 

when min=15 then out=out 'a quarter past' 

when min=20 then out=out 'twenty past' 

when min=25 then out=out 'twenty-five past' 

when min=30 then out=out 'half past' 

when min=35 then out=out 'twenty-five to' 

when min=40 then out=out 'twenty to' 

when min=45 then out=out 'a quarter to' 

when min=50 then out=out 'ten to!' 

when min=55 then out=out 'five to!' 

end 


numbers='one two three four five six'- /, (continuation) ,/ 
"seven eight nine ten eleven twelve ' 
out=out numbers.word(hour) /, add the hour number ,/ 


if min=0 then out=out "o'clock" /, .. and o'clock if exact ,;/ 
say out'.' /x display the final result ,/ 

|e ree esessccesenenene x/ 
/x Subroutine that describes the purpose of the program ,/ 

Fee aae anet ecm x/ 


method tell static 

say 'QTIME will display the current time in real English.' 
say 'Call without any arguments to display the time, or with' 
say '"2?" to display this information. ' 

say ‘British English idioms are used in this program.' 


say /y blank line - we are about to continue and show time ,;/ 
return 


/y Mike Cowlishaw, December 1979 - January 1985 ,/ 
/% NetRexx version March 1996 «if 
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Appendix B - The netrexx.lang Package 


This appendix documents the netrexx.lang package, which includes the classes used for 
creating string objects of type RExx along with several classes that are often used while 
running NetRExx programs. 


This appendix describes the public methods and properties of these classes, as imple- 
mented by the reference implementation. It does not include those *built-in” Methods 
for NetREXx (see page strings in the RExx class that form part of the NetRExx 
language, or those classes and methods that are internal “helper” components (which, 
for example, are used as repositories for rarely-executed code). 


The classes in the netrexx.lang package are: 


¢ The Exception classes (see page 

« RExx (see page 

¢ RexxIO (helper class, see page 

¢ RexxNode (helper class, for indexed strings) 
¢ RexxOperators interface (see page 

¢ RexxParse (helper class, for parse) 

RExxSet (see page 204) 

RexxTrace (helper class, for trace) 
RexxUtil (helper class, for the RExx class) 

¢ RexxWords (helper class, for the RExx class) 


49.1 Exception classes 


The classes provided for exceptions in the netrexx.lang package are all subclasses of 
java.lang.RuntimeException and all have the same content. Each has two constructors: 
one taking no argument and the other taking a string of type java.lang.String, which is 
used for additional detail describing the exception. 


The Exceptions are signalled as follows. 


BadArgumentException signalled when an argument to a method is incorrect. 

BadColumnException signalled when a column number in a parsing template is not 
valid (for example, not a number). 

BadNumericException signalled when a numeric digits instruction tries to set a 
value that is not a whole number, or is not positive, or is more than nine digits. 

DivideException signalled when an error occurs during a division. This may be due to 
an attempt to divide by zero, or when the intermediate result of an integer divide 
or remainder operation is not valid. 
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ExponentOverflowException signalled when the exponent resulting from an opera- 
tion would require more than nine digits. 

NoOtherwiseException signalled whena select construct does not supply an otherwise 
clause and none of expressions on the when clauses resulted in ’1’. 

NotCharacterException signalled when a conversion from a string to a single character 
was attempted but the string was not exactly one character long. 

NotLogicException signalled when a conversion from a string to a boolean was at- 
tempted but the string was neither the string ’0’ nor the string ’1’. 


Other exceptions, from the java.lang package, may also be signalled, for example Num- 
berFormatException or NullPointerException. 


49.2. The RExx class 


The class netrexx.lang.RExx implements the NetRExx string class, and includes the 
“built-in” Methods for NetRExx strings (see page 179). 


Described here are the platform-dependent methods as provided in the reference im- 
plementation: constructors (see page for the class, the methods for arithmetic op- 
erations (see page , and miscellaneous methods (see page intended for general 
use. 


The class netrexx.lang.REXx is serializable. 


49.3 RExx constructors 


These constructors all create a string of type netrexx.lang.REXx. 


RExx(arg=boolean) 
Constructs a string which will have the value ’1’ if arg is 1 (true) or the value ’0’ if 
arg is 0 (false). 

RExx(arg=byte) 
Constructs a string which is the decimal representation of the 8-bit signed binary 
integer arg. The string will contain only decimal digits, prefixed with a leading mi- 
nus sign (hyphen) if arg is negative. A leading zero will be present only if arg is 
zero. 

RExx(arg=char) 
Constructs a string of length 1 whose first and only character is a copy of arg. 

RExx(arg=char[]) 
Constructs a string by copying the characters of the character array arg in sequence. 
The length of the string is the number of elements in the character array (that is, 
arg.length). 

RExx(arg=int) 
Constructs a string which is the decimal representation of the 32-bit signed binary 
integer arg. The string will contain only decimal digits, prefixed with a leading mi- 
nus sign (hyphen) if arg is negative. A leading zero will be present only if arg is 
zero. 
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ReExx(arg=double) 
Constructs a string which is the decimal representation of the 64-bit signed binary 
floating point number arg. (The precise format of the result may change and will be 


defined later.) 


RExx(arg=float) 
Constructs a string which is the decimal representation of the 32-bit signed binary 
floating point number arg. (The precise format of the result may change and will be 


defined later.) 

Rexx(arg=long) 
Constructs a string which is the decimal representation of the 64-bit signed binary 
integer arg. The string will contain only decimal digits, prefixed with a leading mi- 
nus sign (hyphen) if arg is negative. A leading zero will be present only if arg is 
Zero. 


RExx(arg=REXxx) 
Constructs a string which is copy of arg, which is of type netrexx.lang.REXX. arg 
must not be null. Any sub-values (see page are ignored (that is, they are not 
present in the object returned by the constructor). 


RExx(arg=short) 
Constructs a string which is the decimal representation of the 16-bit signed binary 
integer arg. The string will contain only decimal digits, prefixed with a leading mi- 
nus sign (hyphen) if arg is negative. A leading zero will be present only if arg is 
zero. 

RExx(arg=String) 
Constructs a NetRExx string by copying the characters of arg, which is of type 
java.lang.String, in sequence. The length of the string is same as the length of arg 
(that is, arg.length()). arg must not be null. 

RExx(arg=String[]) 
Constructs a NetRExx string by concatenating the elements of the java.lang.String 
array arg together in sequence with a blank between each pair of elements. This may 
be used for converting the argument word array passed to the main method of a 
Java application into a single string. 
If the number of elements of arg is zero then an empty string (of length 0) is re- 
turned. Otherwise, the length of the string is the sum of the lengths of the elements 
of arg, plus the number of elements of arg, less one. 
arg must not be null. 


49.4 Rexx arithmetic methods 


These methods implement the NetRExx arithmetic operators, as described in the sec- 
tion on Numbers and (see page arithmetic. Each corresponds to and implements a 
method in the RExxOperators interface class (see page 


Each of the methods here takes a RExxSet (see page 206) object as an argument. This 
argument provides the numeric settings for the operation; if null is provided for the 
argument then the default settings are used (digits=9, form=scientific). 


201 


For monadic operators, only the RExxSet argument is present; the operation acts upon 
the current object. For dyadic operators, the RExxSet argument and a RExx argument 
are present; the operation acts with the current object being the left-hand operand and 
the second argument being the right-hand operand. For example, under default numeric 
settings, the expression: 


awardt+extra 
(where award and extra are references to objects of type RExx) could be written as: 
award.OpAdd(null, extra) 


which would return the result of adding award and extra under the default numeric 
settings. 


OpAdd(set=RExxSet, rhs=RExx) 
Implements the NetRExx + (Add) operator, and returns the result as a string of 
type RExx. 

OpAnd(set=RExxSet, rhs=REXx) 
Implements the NetRExx & (And) operator, and returns a result (0 or 1) of type 
boolean. 

OpCc(set=RExxSet, rhs=RExx) 
Implements the NetRExx || or abuttal (Concatenate without blank) operator, and 
returns the result as a string of type REXx. 

OpCcblank(set=RExxSet, rhs=REXx) 
Implements the NetRExx blank (Concatenate with blank) operator, and returns the 
result as a string of type REXx. 

OpDiv(set=RExxSet, rhs=RExx) 
Implements the NetRExx / (Divide) operator, and returns the result as a string of 
type RExx. 

OpDivI(set=RExxSet, rhs=REXx) 
Implements the NetRExx % (Integer divide) operator , and returns the result as a 
string of type RExx. 

OpEq(set=RExxSet, rhs=RExx) 
Implements the NetRExx = (Equal) operator, and returns a result (0 or 1) of type 
boolean. 

OpEqS(set=RExxSet, rhs=RExx) Implements the NetRExx == (Strictly equal) opera- 

tor, and returns a result (0 or 1) of type boolean. 

OpGt(set=RExxSet, rhs=RExx) 
Implements the NetRExx > (Greater than) operator, and returns a result (0 or 1) of 
type boolean. 

OpGtEq(set=RExxSet, rhs=REXx) 
Implements the NetRExx >= (Greater than or equal) operator, and returns a result 
(0 or 1) of type boolean. 

OpGtEqS(set=RExxSet, rhs=RExx) 
Implements the NetRExx »= (Strictly greater than or equal) operator, and returns 
a result (0 or 1) of type boolean. 
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OpGtS(set=RexxSet, rhs=REXx) 
Implements the NetRExx » (Strictly greater than) operator, and returns a result (0 
or 1) of type boolean. 

OpLt(set=RExxSet, rhs=RExx) 
Implements the NetRExx < (Less than) operator, and returns a result (0 or 1) of 
type boolean. 

OpLtEq(set=RExxSet, rhs=REXx) 
Implements the NetRExx <= (Less than or equal) operator, and returns a result (0 
or 1) of type boolean. 

OpLtEqS(set=RExxSet, rhs=RExx) 
Implements the NetRExx «= (Strictly less than or equal) operator, and returns a 
result (0 or 1) of type boolean. 

OpLtS(set=RexxSet, rhs=REXx) 
Implements the NetRExx « (Strictly less than) operator, and returns a result (0 or 
1) of type boolean. 

OpMinus(set=RExxSet) 
Implements the NetRExx Prefix - (Minus) operator , and returns the result as a 
string of type REXxx. 

OpMult(set=RexxSet, rhs=REXx) 
Implements the NetRExx * (Multiply) operator , and returns the result as a string 
of type REXx. 

OpNot(set=RExxSet) 
Implements the NetRExx Prefix \ (Not) operator, and returns a result (0 or 1) of 
type boolean. 

OpNotEq(set=RExxSet, rhs=REXx) 
Implements the NetRExx \= (Not equal) operator, and returns a result (0 or 1) of 
type boolean. 

OpNotEqS(set=RExxSet, rhs=REXx) 
Implements the NetRExx \== (Strictly not equal) operator, and returns a result (0 
or 1) of type boolean. 

OpOr(set=RExxSet, rhs=REXX) 
Implements the NetRExx | (Inclusive or) operator, and returns a result (0 or 1) of 
type boolean. 

OpPlus(set=RExxSet) 
Implements the NetRExx Prefix + (Plus) operator , and returns the result as a string 
of type REXx. 

OpPow(set=RExxSet, rhs=RExx) 
Implements the NetRExx ** (Power) operator , and returns the result as a string of 
type RExx. 

OpRem(set=RExxSet, rhs=REXx) 
Implements the NetRExx // (Remainder) operator , and returns the result as a string 
of type REXx. 

OpSub(set=RExxSet, rhs=REXx) 
Implements the NetRExx - (Subtract) operator, and returns the result as a string of 
type RExx. 
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OpXor(set=RExxSet, rhs=REXx) 
Implements the NetRExx && (Exclusive or) operator, and returns a result (0 or 1) 
of type boolean. 


49.5 RExx miscellaneous methods 


These methods provide standard Java methods for the class, together with various con- 
versions. 


charAt(offset=int) 
Returns the character from the string at offset (that is, if offset is 0 then the first 
character is returned, etc.). The character is returned as type char. 
If offset is negative, or is greater than or equal to the length of the string, an excep- 
tion is signalled. 

equals(item=Object) 
Compares the string with the value of item, using a strict character-by-character 
comparison, and returns a result of type boolean. 
If item is null or is not an instance of one of the types REXx, java.lang.String, 
or char[], then 0 is returned. Otherwise, item is converted to type RExx and the 
OpEdS (see page 202) method (or equivalent) is used to compare the current string 
with the converted string, and its result is returned. 

hashCode() 
Returns a hashcode of type int for the string. This hashcode is suitable for use by 
the java.util. Hashtable class. 


toboolean() 
Converts the string to type boolean. If the string is neither ”0” nor 
NotLogicException (see page is signalled. 

tobyte() 
Converts the string to type byte. If the string is not a number, has a non-zero deci- 
mal part, or is out of the possible range for a byte (8-bit signed integer) result then 
a NumberFormatException is signalled. 

toByteArray() 

3.04 Converts the string to type byte[], observing the standard codepage for the plat- 

form. 

tochar() 
Converts the string to type char. If the string is not exactly one character in length 
then a NotCharacterException (see page is signalled. 

toCharArray() 
Converts the string to type char[]. A character array object of the same length as the 
string is created, and the characters of the string are copied to the array in sequence. 
The character array is then returned. 

todouble() 
Converts the string to type double. If the string is not a number, or is out of the 
possible range for a double (64-bit signed floating point) result then a Number- 
FormatException is signalled. 
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tofloat() 
Converts the string to type float. If the string is not a number, or is out of the 
possible range for a float (32-bit signed floating point) result then a NumberFor- 
matException is signalled. 

toint() 
Converts the string to type int. Ifthe string is not a number, has a non-zero decimal 
part, or is out of the possible range for an int (32-bit signed integer) result then a 
NumberFormatException is signalled. 

tolong() 
Converts the string to type long. If the string is not a number, has a non-zero dec- 
imal part, or is out of the possible range for a long (64-bit signed integer) result 
then a NumberFormatException is signalled. [%hide 

toRExx(arg=char[]) static 
Takes arg, an array of characters, and returns a copy of it as a string of type net- 
rexx.lang.REXx. If the argument is null, then null is returned (not a null string). 
This is a static method (a function). 

toRExx(arg=String) static 
Takes arg, a java.lang.String, and returns a copy of it as a string of type net- 
rexx.lang.REXx. If the argument is null, then null is returned (not a null string). 
This is a static method (a function). 

toshort() 
Converts the string to type short. If the string is not a number, has a non-zero 
decimal part, or is out of the possible range for a short (16-bit signed) result then 
a NumberFormatException is signalled. 

toString() 
Converts the string to type java.lang.String. A String object of the same length as 
the string is created, and the characters of the string are copied to the new string in 
sequence. The String is then returned. 


49.6 The RExxIO class 


The RExxIO class implements a number of helper methods, for example RexxI0. say, a 
call to which is generated when a program contains a say statement. 


Ask() static returns RExx 
get a line of text from the console 
AskOne() static returns REXx 
get one character from the console (still requires a return) 
Say(obj=Object) static returns boolean 
put a line out to the console If the line ends in the NUL character (’ 
- or’ 
0’) then no line termination is provided (and the NUL is deleted). If the write suc- 
ceeds 0 is returned, otherwise 1 is returned. 
Say(str=String) static returns boolean 
put a line out to the console 
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Say(line=RExx) static returns boolean 
put a line out to the console 
Say(c=char) static returns boolean 
put a line out to the console 
Say(n=long) static returns boolean 
put a line out to the console 
Say(f=float) static returns boolean 
put a line out to the console 
Say(d=double) static returns boolean 
put a line out to the console 
Say(b=boolean) static returns boolean 
put a line out to the console 
Say(aline=char[]) static returns boolean 
put a line out to the console 
setOutputStream(out=OutputStream) static 
change the outputstream for say to use 
pushOutputStream(out=OutputStream) static 
push an outputstream on the decque, for say to use 
popOutputStream() static 
remove an outputstream from the decque, will not be used anymore 
File(nm) returns RExxIO 
define a file to the RexxXIO instance 
forEachline(c=LineHandler) 
define a callback that calls an instance of the LineHandler interface 
forEachline(c=LineHandler,numLines) 
define a callback that calls an instance of the LineHandler interface that is only 
called a number of times as specified in numLines 


49.7 The RExxOperators interface class 


The RExxOperators interface class defines the signatures of the methods that imple- 
ment the NetRExx (and RExx) operators. These methods are described in the section 
RExx arithmetic methods (see page 


In the future this interface may be used to allow the overloading of operators for objects 
of types other than Rexx. The current NetRexx language definition does not permit 
operator overloading. 


49.8 The RExxSet class 


The RExxSet class is used to provide the numeric settings for the methods described in 
the section RExx (see page arithmetic methods. When provided, a RExxSet Object 
supplies the numeric settings for the operation; when null is provided then the default 
settings are used (digits=9, form=SCIENTIFIC). 
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49.8.1 Public properties 


These properties supply the numeric settings and certain values they may take. After con- 
struction, the digits and form values should only be changed by using the setDigits 
and setForm methods. 


DEFAULT_DIGITS 
A constant of type int that describes the default number of digits for a numeric 
operation (9). 

DEFAULT_FORM 
A constant of type byte that describes the default exponential format for a numeric 
operation (SCIENTIFIC). 

digits 
A value of type int that describes the numeric digits to be used for a numeric oper- 
ation. The Rexx arithmetic (see page methods:ea. use this value to determine 
the significance of results. digits must always be greater than zero. 

ENGINEERING 
A constant of type byte that signifies that engineering exponential formatting 
should be used for a numeric operation. 

form 
A value of type byte that describes the exponential format to be used for a nu- 
meric operation. The Rexx arithmetic (see page methods:ea. use this value to 
determine the formatting of results that require an exponent. form must be either 
ENGINEERING or SCIENTIFIC. 

SCIENTIFIC 
A constant of type byte that signifies that scientific exponential formatting should 
be used for a numeric operation. 


49.8.2 Constructors 


These constructors are used to set the initial values of a RExxSet object. 


RexxSet() 
Constructs a RexxSet object which has default digits and form properties. 
RExxSet(newdigits=int) 
Constructs a RExxSet object which has its digits property set to newdigits and its 
form property set to DEFAULT_DIGITS. 
RexxSet(newdigits=int, newform=byte) 
Constructs a RExxSet object which has its digits property set to newdigits and its 
form property set to newform. 
RexxSet(arg=RExxSet) 
Constructs a RExxSet object which is copy of arg, which is of type netrexx.lang.REXxSet. 
arg must not be null. 


49.8.3 Methods 


The RexxSet class has the following additional methods: 
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formword() 
Returns a string of type netrexx.lang.REXxx that describes the form property. This 
will either be the string engineering’ or the string ’scientific’, corresponding to the 
form value ENGINEERING or SCIENTIFIC, respectively. 

setDigits(newdigits=REXxx) 
Sets the digits value for the RExxSet object, from newdigits, after rounding and 
checking as defined for the numeric instruction; newdigits must be a positive whole 
number with no more than nine digits. No value is returned. 

setForm(newformword=RExx) 
Sets the form value for the RExxSet object, from newformword. This must equal 
either the string engineering’ or the string ’scientific’, corresponding to the form 
value ENGINEERING or SCIENTIFIC, respectively. No value is returned. 
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Encodings,of characters, ha 





END clause,specifying control variable, ka 
End condition of a LOOP loop,, 7 
End-of-file character,, fig 

Engineering notation, fod, 
ENGINEERING property, 

ENGINEERING value for NUMERIC FORM,, 
EOF character,, 

Equality,of objects, hg] 
Equality,testing of, hg] 

equals method,, 

Errors during arithmetic, 

Escape sequences in strings, Ry 

Euro character,, pal 

Euro character,in symbols, pj 
Evaluation,of expressions, 

Evaluation,of terms, 

Example,Hello World, 

Example,of constructors, hq 

Example,of exception handling, 
Example,of two classes, 

Example, program, 

Exception, BadArgumentException, 
Exception,BadColumnException, |199 
Exception,BadNumericException, |199 
Exception,DivideException, 
Exception, ExponentOverflowException, 
Exception,NoOtherwiseException, 200 






Exception,NotCharacterException, 
Exception,NotLogicException, 20Q 
Exception,NullPointerException, 





Exception,NumberFormatException, 
Exceptions, 
Exceptions,after CATCH clause, 

Exceptions,after FINALLY clause, 





Exceptions, checked, 
Exceptions,during arithmetic, 
Exceptions,during conversions, Z| 
Exceptions, Listed on METHOD instruction, b7| 
Exceptions, raising, 
Exceptions,signalling, 

Exceptions, throwing, 

Exclusive OR, logical operator, bq 
EXISTS method, {186 

EXIT instruction,, 

EXPLICIT option, 

Exponential notation,, FE, fod, fi55], ir) 
Exponential notation,definition, [62 
Exponential notation,in symbols, 
Exponentiation,definition, 
ExponentOverflowException,, [200 
Expressions,evaluation, a7 
Expressions,examples, bq 
Expressions,results of, 7 

EXTENDS,on CLASS instruction, [71] 

Extra digits,in numbers, 

Extra digits,in numeric symbols, Ril, pq 
Extra digits,in symbols, 

Extra letters, in symbols, Raj 
Extracting,a sub-string, 
Extracting,words from a string, 


False value,, bq 

File method,, 

Final classes, fl 

Final methods,, 

FINAL,on CLASS instruction, [7g 
FINAL,on METHOD instruction, 
FINALLY,on DO instruction, 74] 
FINALLY,on LOOP instruction, Bq 
FINALLY,on SELECT instruction, 
FINALLY, reached by LEAVE, [83) 
FINALLY ,use of, 


Finding a mismatch using COMPARE,, 


Finding a string in another string,, isd, 


Fixed size, of arrays, 

Floating-point numbers, binary,, 
Flow control,abnormal, with SIGNAL, 
Flow control,with DO construct, 
Flow control,with IF construct, fra 
Flow control,with LOOP construct, 
Flow control,with SELECT construct, 
FOR,phrase of LOOP instruction, 5] 
FOR,repetitor on LOOP instruction, 5 
forEachline method, 206 

FOREVER, Loops, 4 

FOREVER, repetitor on LOOP instruction, ee 
Form feed character, fg 


form property, 





FORM,option of NUMERIC instruction, fod, 


FORM,special word, 

FORMAT, method, 

FORMAT, option, 
Formatting,numbers for display, {186 
Formatting,numbers with TRUNC, 
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Formatting,of output during tracing, 
Formatting, text centering, 
Formatting,text left justification, 





Formatting,text right justification, 
Formatting, text spacing, 
formword() method,, 


Full name,of classes, 
Fully-qualified name, of classes,, 


Functions,numeric arguments of, 
Functions,return from, 
Functions,used by classes, iz 


Glyphs,, fd 
Group, DO, 
Guard digit in arithmetic,, 


hashCode method, 204 

Hexadecimal numeric symbol,, pd, pal 
Hexadecimal,checking with DATATYPE, 
Hexadecimal,conversion to binary, fio4| 
Hexadecimal,conversion to character, ft95} 
Hexadecimal,conversion to decimal, 
Hexadecimal,digits in escapes, 
Hexadecimal,escape sequence, 

Hyphen,as continuation character, 


IF instruction,, ira 

IMPLEMENTS,on CLASS instruction, 
Implied semicolons,, 

IMPORT instruction,, [rg] 
Imports,automatic, gq 
Imports,explicit, [rg] 

Indefinite loops, 5], gq 

Indention during tracing,, 

Index strings, for sub-values, 

Index strings,testing for, 
Indexed references, arrays, eq 

Indexed references,in terms, By 
Indexed references, indexed strings, 
Indexed strings, a] 

Indexed strings, copying, 

Indexed strings,merging, 

Indexed strings,testing for, 
Indirect properties,, 

INDIRECT,on PROPERTIES instruction, 
Inequality, testing of, hg 

Infinite loops, 5 

INHERITABLE,on METHOD instruction, bal 
INHERITABLE,on PROPERTIES instruction, 
Initializing arrays, 

INSERT method,, [188 

Inserting a string into another,, 
Instance, of a class, 

Instructions,, 5] 

Instructions, Annotate, 7 
Instructions, assignment, bs), 7 
Instructions,CLASS, 9] 
Instructions,DO, 

Instructions, EXIT, 

Instructions, IF, ira 

Instructions, IMPORT, [rg] 


Instructions, ITERATE, gy 
Instructions, keyword, bo, 5] 
Instructions, LEAVE, g3 

Instructions, LOOP, 
Instructions,METHOD, b3, 
Instructions,method call, 5] 
Instructions,NOP, bg 
Instructions,NUMERIC, 
Instructions,OPTIONS, 
Instructions, PACKAGE, 
Instructions, PARSE, 
Instructions, PROPERTIES, [11], 
Instructions, RETURN, 
Instructions, SAY, 

Instructions, SELECT, 
Instructions,SIGNAL, 
Instructions, TRACE, 

Integer division, 

Integer division,definition, 
Integers, binary, 

Interface classes, 

Interface classes,properties in, 
INTERFACE,on CLASS instruction, [rg 
Interfaces, implemented by classes, fr 
Internal functions,return from, [115} 
Interpreter options,, 

ITERATE instruction,, gy 

ITERATE instruction,use of variable on, gi] 


JAVA option, 
Java,in reference implementation, 


JavaBean properties, 
JAVAC option, 


KEEPASJAVA option, 
Keyword instructions, b5, 5] 


Keywords,, 
Keywords,mixed case, 65) 


LABEL,on DO instruction, fr 

LABEL,on LOOP instruction, gg 

LABEL,on SELECT instruction, 

Language processor options, |10 

LASTPOS method,, [188 

Leading blanks,removal with STRIP method, 
fol 

Leading zeros,adding with the RIGHT method, 

Leading zeros,removal with STRIP method, 

LEAVE instruction, 

LEAVE instruction,use of variable on, B3 

LEFT method, [188 

LENGTH, method, 

Length,of arrays, 

Length,of comments, kg 

LENGTH, special word, BS, 

Letters,checking with DATATYPE, {183 

Line comments,, ir) 

Line ends, effect of, 
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Line feed character,escape sequence, by 
Line numbers, in tracing, 
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Line, displaying, 

lists, 

Literal patterns,, 

Literal strings, | 

Literal strings,in terms, Bi 

Literals, binary,, 

Local variables,, 9 

Locating,a string in another string, isd, 
Locating,a word or phrase in a string, fi94) 
Logical operations, 

LOGO option, 

Loops,active, i, 

Loops,execution model, bq 

Loops,in binary classes and methods, feq 
Loops, Label, ig 

Loops,modification of, gy 

Loops,naming of, sg 

Loops, repetitive, 5), Bq 

Loops, termination of, 3 

LOWER method,, [188 

Lowercase,checking with DATATYPE, 
Lowercase,names, 


Lowercasing strings, 


Mantissa of exponential numbers, iy) 
Matching methods,, Bg 

Mathematical method,ABS, 
Mathematical method,DATATYPE options, 
Mathematical method, FORMAT, 
Mathematical method,MAX, 
Mathematical method,MIN, 
Mathematical method, SIGN, 

MAX method,, 

Merging indexed variables, 
Method call instructions, Bg, 5] 
METHOD instruction, 

Method,, 

Method, built-in, ABBREV, 

Method, built-in, ABS, 


Method, built-in,B2D, 
Method, built-in,B2X, 
Method, built-in,C2D, 
Method, built-in,C2X, 
Method, built-in, CENTER, 
Method, built-in, CENTRE, 
Method, built-in, CHANGESTR, 
Method, built-in, COMPARE, 
Method, built-in,COPIES, 


Method, built-in,COPYINDEXED, [182 


Method, built-in, COUNTSTR, 
Method, built-in,D2B, 
Method, built-in,D2C, 
Method, built-in,D2X, 


Method, built-in,DATATYPE, 
Method, built-in,DELSTR, 
Method, built-in,DELWORD, [1 
Method, built-in,EXISTS, 
Method, built-in, FORMAT, 
Method, built-in, INSERT, 
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Method, built-in,LASTPOS, [1898 Method, OpMult, 203] 

Method, built-in,LEFT, Method, OpNot, 

Method, built-in,LENGTH, {188 Method,OpOr, 

Method, built-in, LOWER, Method,OpPlus, 

Method, built-in,MAX, Method, OpPow, 

Method, built-in,MIN, Method, OpRem, 

Method, built-in, OVERLAY, Method, OpSub, 

Method, built-in,POS, Method, OpXor, [204 

Method, built-in,REVERSE, Method, popOutputStream, 
Method, built-in,RIGHT, Method, pushOutputStream, 
Method, built-in, SEQUENCE, Method, Say, 

Method, built-in,SIGN, fod Method, setDigits (Rexx), 
Method, built-in,SPACE, Method, setForm(Rexx) , 
Method, built-in,STRIP, Method,short name of, b3 
Method, built-in,SUBSTR, Method, starting, 

Method, built-in, SUBWORD, Method, toboolean, [204 
Method, built-in, TRANSLATE, Method, tobyte, [204 

Method, built-in, TRUNC, Method, tobytearray, 204 
Method, built-in,UPPER, Method,tochar, 204 

Method, built-in, VERIFY, Method, todouble, 204 

Method, built-in,WORD, f94| Method,tofloat, |205 

Method, built-in,WORDINDEX, [194 Method, toint, 

Method, built-in,WORDLENGTH, [194 Method, tolong, 

Method, built-in,WORDPOS, Method, toRexx, 

Method, built-in,WORDS, Method,toshort, 205} 

Method, built-in,X2B, fi94] Method, toString, 

Method, built-in, X2C, iE] Methods,, Ba 

Method, built-in,X2D, fos Methods, abstract, irl, EE | 
Method,argument variables, | Methods, arguments of, Z| 
Method, Ask, Methods, binary, bq 

Method ,AskOne, Methods, constant, 

Method, body of, Methods, constructor, hal, b3 
Method,calls in terms, By Methods, duplicate, 

Method, charAt, 204 Methods, final, bl 
Method,definition, Methods, inheritable, pal 
Method,equals, [204 Methods, invocation of, Bq 
Method,File, 206 Methods, native, p5| 

Method, forEachline, Methods, overloading, b7| 
Method, formword(), Methods,overriding, 
Method ,hashCode, Methods, private, pal 
Method,names, case of, Z| Methods, protected, bq 

Method ,NotEq, [203 Methods, public, pa] 
Method,NotEqS, 203 Methods,resolution of, Bg 
Method, OpAdd, Methods, return values, ba 
Method, OpAnd, Methods,searching for, Bg 
Method ,OpCc, /202) Methods, shared, ba] 

Method ,OpCcblank, Methods, special, 

Method, OpDiv, Methods, standard, 
Method,OpDivI, 202 Methods,static, b5| 

Method, OpEq, METHODS, TRACE setting, 126 
Method,OpEqS, [202 MIN method,, 

Method ,OpGt, )202) Minor classes, pg 
Method,OpGtEq, 202 Minor classes,constructing, 
Method, OpGtEqS, Minor classes,naming of, 
Method, OpGts, Minor classes,nesting of, 
Method,OpLt, )203 Minor classes,restrictions, 138 
Method, OpLtEq, Mixed case,checking with DATATYPE, 
Method,OpLtEqS, 203} Mixed case,names, pal 
Method,OpLtS, 203 Model,of loop execution, bd 
Method,OpMinus, Monadic (prefix) operators,, h7| 
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Moving characters, with TRANSLATE method, NOSTRICTSIGNAL option, 
iy] NOSYMBOLS option, [105 
Multiplication,definition, [158 NOT operator,, 


Notation,engineering, Lod, 
Names, special,class, Notation,scientific, [Lol, 





Names, special,sourceline, Notations,in text, 
Names,case of, pal Notations, syntax, fi5| 
Names,of variables, 67 NotCharacterException,, 
Names,on ITERATE instructions, qj NotEq method,, 
Names,on LEAVE instructions, NotEqS method,, 

Names, special/ask, NotLogicException,, 200 
Names ,special/digits, NOTRACE option,, [105 
Names,special/form, NOUTF8 option,, 

Names ,special/length, NOVERBOSE option, 
Names ,special/null, Null character,escape sequence, pil 
Names ,special/source, Null clauses, 5 

Names, special/super, Null instruction, NOP,, 
Names, special/this, NULL special word, 


Names, special/trace, 


Names, special/version, 






Null strings, Rg 
NullPointerException, 200 


Native methods, NumberFormatException,, 
NATIVE,on METHOD instruction, 95] Numbers, fa, 

Negation,of logical values, bq Numbers, arithmetic on, hal, fi55, 
Negation,of numbers, hal Numbers,as symbols, 

Nesting of comments, ba Numbers, checking with DATATYPE, 
netrexx. lang package, fog Numbers,comparison of, hg, 





netrexx. lang,Exceptions, Numbers,conversion to character, fi35], | 
netrexx.lang,Rexx arithmetic methods, Numbers,conversion to hexadecimal, 
netrexx.lang,Rexx class, Numbers, definition, fi54, fed 


netrexx.lang,Rexx constructors, 200 Numbers,examples of by] 
? > 





netrexx.lang,Rexx miscellaneous methods, 204 Numbers, formatting for display, 
netrexx.lang,RexxI0 class, Numbers, in LOOP instruction, 5] 
netrexx.lang,RexxOperators class, 2 Numbers, rounding, 
netrexx.lang,RexxSet class, 206 Numbers, truncating, 
netrexx. lLang,RexxSet constructors, Numbers,use of by NetRexx, 
netrexx. Lang,RexxSet methods, Numeric symbols ka, Bu 

” 





netrexx. lang,RexxSet properties, 207 Numeric symbols,binary, bg 


Newline character,escape sequence, pil Numeric symbols, hexadecimal, pa 


NOBINARY option,, NUMERIC, DIGITS, 
NOCOMMENTS option, [103 NUMERIC, FORM, 
NOCOMPACT option,, NUMERIC, in binary classes and methods, [167 


NOCONSOLE option, NUMERIC, instruction, 
NOCROSSREF option, Numeric,part of a number, fi54, 
NODECIMAL option, 

NODIAG option, 

NOEXPLICIT option, 

NOFORMAT option, 

NOJAVA option, 

NOLOGO option, 
NoOtherwiseException,, 200 

NOP instruction,, 

NOREPLACE option, 

Normal comparative operators, gl 
NOSAVELOG option, 
NOSOURCEDIR option, 
NOSTRICTARGS option, 
NOSTRICTASSIGN option, 
NOSTRICTCASE option, 
NOSTRICTIMPORT option, 
NOSTRICTPROPS option, 


bjects,comparing, hg] 
bjects,constructing, hl 
bjects,equality, hg] 
FF,TRACE setting, 
pAdd method,, [202] 
pAnd method,, 
pCc method,, 
pCcblank method,, 202] 
pDiv method,, 
pDivI method, 202 
pEq method,, 
pEqS method,, 

perators,, 7 

perators,arithmetic, hal, fis], 
perators,blank, hal, 


perators,characters used for, 
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Operators, comparative, kg, 
Operators,composition of, a7 

Operators, concatenation, hg 

Operators, logical, 
Operators,precedence (priorities) of, bq 
Operators, type, bq 

OpGt method,, 

OpGtEq method,, 
OpGtEqS method,, 
OpGtS method,, 
OpLt method, 22 
OpLtEq method, 
OpLtEqS method 
OpLtS method,, 
OpMinus method 
OpMult method, 
OpNot method,, 
OpOr method,, 2 
OpPlus method, 
OpPow method,, 
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OpRem method,, 
OpSub method,, 
Option words, 
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Optional arguments, bal 

OPTIONS, instruction, 

Options,on command line, 

OpXor method,, 

OR, Logical exclusive, bd 

OR, Logical inclusive, bd 

Over loops, gg 

OVER repetitor on LOOP instruction,, ee 
Overflow, arithmetic, fre4 

OVERLAY method,, [189 

Overlaying a string onto another,, 
Overloaded methods,, ba 

Overriding methods, hg 


PACKAGE instruction,, 


Package,, Ra, 

Package,name of, [rg], 

Package, netrexx. Lang, i 

Packing a string,with B2D, 

Packing a string,with B2X, 

Packing a string,with X2C, 

Parent class,, [135] 

Parent object, 

Parent,of dependent object, 

PARENT,Special word, 

Parentheses,adjacent to blanks, 

Parentheses,in expressions, 7, 

Parentheses,in method calls, Bal, B7 

Parentheses,in parsing templates, 

Parentheses,in terms, By 

Parentheses ,omitting from method calls, Ba, 
pa 

PARSE, instruction, 


PARSE, parsing rules, 
Parsing templates, in PARSE instruction, 


Parsing,absolute columns, 
Parsing,definition, [148 
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Parsing,general rules, faq, 


Parsing, introduction, 
Parsing,literal patterns, 


Parsing,positional patterns, 
Parsing,selecting words, 
Parsing,variable patterns, 
Period,as placeholder in parsing, 
Period,in numbers, 

Period,in terms, Bal 

poOutputStream method,, 

POS position method,, 


Positional patterns,, 
Power operator,, hg 


Power operator,definition, 
Powers of ten in numbers,, fal, 162) 
Precedence of operators, 
Precision,arbitrary, 
Precision,of arithmetic, 
Prefix operators, h7| 

Prefix operators,+, hal 

Prefix operators,+/with types, bq 


Prefix operators,-, 
Prefix operators,-/with types, fq 


Prefix operators,\, 

Prefix operators,\/with types, bq 
Prefix operators,arithmetic, 158 
Primitive types,, Rd, iE 

Primitive types,conversions, 3 
Priorities of operators, bq 
PRIVATE,on CLASS instruction, [79 
PRIVATE,on METHOD instruction, | 
PRIVATE,on PROPERTIES instruction, 


Program, filename of, 
Program,prolog, 


Program,structure, 
Programmer’s model of LOOP,, bg 
Programs,, 

Programs,examples, [t97| 
Programs,structure, 

Prolog, of a program, 
PROPERTIES instruction, [ii], 
Properties,, ed, a, 
Properties,case of names, 
Properties,constant, 


Properties,deprecated, 
Properties, for JavaBeans, 


Properties,in dependent classes, 
Properties,in interface classes, 
Properties,in minor classes, 138 
Properties, indirect, 

Properties, inheritable, 
Properties, initialization, 
Properties,modifiers, 
Properties,naming, 
Properties,private, [112 
Properties,public, {112 
Properties,shared, {112 
Properties,static, [112 


Properties, transient, 
Properties,unused, 


Properties,visibility, 
Properties,volatile, 

Property ,DEFAULT_DIGITS, 
Property, DEFAULT_FORM, 
Property,digits, [207 

Property, ENGINEERING, 
Property, form, 

Property, SCIENTIFIC, 
PROTECT,on DO instruction, fr] 
PROTECT,on LOOP instruction, bq 
PROTECT,on METHOD instruction, bq 
PROTECT,on SELECT instruction, 
Protected methods,, bq 

PUBLIC, on CLASS instruction, [7q 
PUBLIC,on METHOD instruction, p4 
PUBLIC,on PROPERTIES instruction, 
Pure numbers,, |162) 

pushOutputStream method,, 


qtime example program,, fio7 
Qualified name, of classes, 
Qualified types, py 

Quotes in strings, 


Rexx(boolean) constructor, 200 
Rexx(byte) constructor,, 
Rexx(char) constructor,, 
Rexx(char[]) constructor,, 
Rexx(double) constructor,, 
Rexx(float) constructor,, 
Rexx(int) constructor,, 
Rexx(long) constructor, 
Rexx (Rexx) constructor,, 
Rexx(short) constructor,, 
Rexx(String) constructor,, 
Rexx(String[]) constructor, 
Rexx, arithmetic, 

Rexx, class/NetRexx strings, 








Rexx,class/conversions, fa] 

Rexx,class/methods of, 

Rexx,class/use by PARSE, 

RexxSet() constructor,, 

RexxSet (int) constructor,, 

RexxSet(int,byte) constructor,, 

RexxSet (RexxSet) constructor,, 

Raising exceptions, 

Re-ordering characters,with TRANSLATE 
method, 

Real numbers, binary, fe 

Reference implementation,, 

References,in terms, Bi 

References,null, 

References,to arrays, kb 

References,to current object, fad, 

References,to indexed strings, 

References,to methods, Ba 

Relative column specification in parsing,, 

Relative positional pattern,, 


Remainder operator,, 





Remainder operator,definition, 


Remainder operator;.pi ,Integer division; .pi 


/Exponentiation, hg 
Repeating a string with COPIES,, 
Repetitive lLoops,, Bq 
Repetitor phrase, Bq 
REPLACE option, 
Replacing strings,using CHANGESTR, 
Replacing strings,using TRANSLATE, 
Required arguments,, pal 
Resolution of methods,, Ba 
Results,of methods, by 
Results, returned by RETURN, 
Results,size of, 7 
RESULTS, TRACE setting, 
Return character,escape sequence, Rij 
Return code, setting on exit, 
RETURN instruction, 
Return string, setting on exit, 
Return Types, 
RETURNS,on METHOD instruction, b7| 
REVERSE method, [190 
RIGHT method, 
Rounding,, 
Rounding, definition, [158 
Rounding,when numbers used, 
Running off the end of a program, 


SAVELOG option,, {105} 

Say method,, 

SAY, instruction, 
Scientific notation, fod, 


SCIENTIFIC property, 
SCIENTIFIC value for NUMERIC FORM, 


Search order,for methods, Bg 

Search order,for term evaluation, 

Searching a string for a word or phrase, 
bsg, 

Select, Label, 

Select,naming of, 

Semicolons,, 

Semicolons,can be omitted, 

Semicolons, implied, 

SEQUENCE method, 


setDigits(Rexx) method, 





setForm(Rexx) method,, 
SHARED,on CLASS instruction, [79 
SHARED,on METHOD instruction, [4| 
SHARED,on PROPERTIES instruction, 
Short name,of classes, kg, 

Short name,of methods, b3 

SIGN method,, 

SIGNAL instruction,, 

Signals, [eg 

SIGNALS,on METHOD instruction, b7 
Significand of exponential numbers, freq 
Significant digits, in arithmetic, 
Signs in parsing templates,, 

Simple DO group, 

Simple number,, pq 


Simple repetitor phrase, gd 

Simple terms, Bal 

Single-quote,escape sequence, Raj 
Single-quote,string delimiter, Rg 

SOURCE special word,, 

SOURCEDIR option, 

SOURCELINE, special word, 

SPACE method,, 

Special characters, bg 

Special characters,used for operators, pq 
Special methods,, 

Special methods, super, 37, 

Special methods,this, 

Special words, 
Special words,ask, 
Special words,class, 
Special words,digits, 
Special words, form, 
Special words, length, 
Special words,null, [140 
Special words,parent, 
Special words,source, 
Special words,sourceline, 
Special words,super, 
Special words,this, 37, 


Special words,trace, 


Square brackets,in array initializers, Ba, 
b3 

Square brackets,in indexed references, By 

Standard classes,, 

Standard methods,, 

Static methods, 5 

Static methods,used by classes, fr 

Static variable typing,, | 

STATIC,on METHOD instruction, 

STATIC,on PROPERTIES instruction, 

stderr, used by TRACE,, 

stdin, reading with ASK, 

stdout, writing to with SAY,, 

Strict comparative operators,, hg 

STRICTARGS option, 

STRICTASSIGN option, 

STRICTCASE option, 

STRICTIMPORT option, 

STRICTPROPS option, 

STRICTSIGNAL option, 

Strings, Rg 

Strings,as literal constants, Rg 












Special words,version, 





Strings,comparison of, kg 
Strings,concatenation of, hg 
Strings,escapes jin, Ri 
Strings,in terms, 
Strings, indexed, al 

Strings, length of, 
Strings, lowercasing, [188 
Strings,moving with TRANSLATE method, iy] 
Strings,null, | 
Strings,quotes jin, 
Strings,sub-values of, ky 
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Strings,types of, Z| 
Strings,uppercasing, ft93} 
Strings,verifying contents of, 
STRIP method, 

Structured Lists, [175 

Stub, of term, Bq 
Sub-expressions, in terms,, By 
Sub-keywords,, 5] 

Sub-string, extracting,, fioq 
Sub-values, of strings, ky 
Subclass of a class, fr] 
Subroutines, calling, Ba 
Subroutines,passing back values from, 
Subroutines,return from, 
Substitution,in expressions, 7 
SUBSTR method, 
Subtraction,definition, [158 
SUBWORD method,, 
SUPER,Special method, 37, 
SUPER,Special word, {140 
Superclass of a class, fl 
Symbol characters,checking with DATATYPE, 
SYMBOLS option,, {105} 

Symbols,, bi 

Symbols,assigning values to, 7 
Symbols,case of, pal 

Symbols,in terms, By 
Symbols,numeric, pd, By 
Symbols,use of, 

Symbols,valid names, Rij 

Syntax diagrams,notation for, 
Syntax notation, 
System-dependent options,, 


Tab character,, 


Tab character,escape sequence, yj 
Tabulation character,, fg 
Templates, parsing,general rules, 





Templates, parsing,in PARSE instruction, 


Ten, powers of, 

Terminal, writing to with SAY,, 
Terms,, By, 7 

Terms, compound, Bq 
Terms,evaluation of, 

Terms,in assignments, kg 

Terms,on left of =, 
Terms,parsing of, 
Terms,simple, By 

Terms,stub of, Bq 

Testing for indexed variables, 
THEN, following IF clause, fra 
THEN, following WHEN clause, 
THIS,special method, 

THIS, special word, [137], 
Thread, tracing, 

Threads, 

TO phrase of LOOP instruction,, 5] 
toboolean AskOne,, 205 


toboolean method,, 





tobyte method,, 
tobytearray method, 
tochar method, 204 
todouble method,, 
tofloat method,, 
toint method,, 
Tokens,, kd 

tolong method,, 
toRexx method,, 
toshort method,, 
toString method,, 
Trace setting, 
Trace setting,altering with TRACE 
instruction, 
Trace,context, 


TRACE, instruction, 
TRACE option, {105} 
TRACE, special word, 
Tracing,clauses, 

Tracing,data identifiers, 
Tracing,execution of programs, {125} 
Tracing, line numbers, 


Tracing,variables, [124 





Trailing blanks,removal with STRIP method, 


oy 
Trailing zeros, 
TRANSIENT,on PROPERTIES instruction, 
TRANSLATE method, 
Translation,with TRANSLATE method, [92 
Trapping of exceptions,, 
True value,, bq 
TRUNC method, 
Truncating numbers, ft92 
Types, 27 
Types,checking instances of, fq 
Types, checking with DATATYPE, 
Types,concatenation of, bg 
Types, conversions, 
Types,declaring, 3 
Types,dimensioned, 
Types,of terms, h7| 
Types,of values, h7| 
Types,operations on, bq 
Types, primitive, Ra, ie 
Types, qualified, p7| 
Types,simplification, hg 





Underflow, arithmetic, fe4 
Underscore,in symbols, by 
Unicode,coded character set, 
Unicode,escape sequence, 
Unicode,UTF-8 encoding, 

Unpacking a string,with C2xX, |183 
Unpacking a string,with X2B, 
UNTIL phrase of LOOP instruction, 
UNUSED,on PROPERTIES instruction, 
UPPER method,, 

Uppercase,checking with DATATYPE, 
Uppercase,names, pal 

Uppercasing strings, fi93 
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UTF-8 encoding,, 


UTF8 option, 


Variable reference,in parsing template, 


Variables, 7 
Variables,controlling loops, 7 





Variables,in parsing patterns, 
Variables, indexed, a] 
Variables, local, 9 
Variables,method arguments, 9 
Variables,names of, 7 
Variables,parsing of, 
Variables,properties, bg 
Variables,scope of, 9] 
Variables,setting new value, 7 
Variables,static typing of, 9 
Variables,subscripts, bi 
Variables,type of, 7 

Variables,valid names, ba 
Variables,visibility, b9 

VERBOSE option, 

VERBOSEn option, 

VERIFY method, 

VERSION special word,, 
Visibility,of classes, ira 
Visibility,of methods, p4 
Visibility,of properties, 
VOLATILE,on PROPERTIES instruction, 





WARNEXITO option, 

Well-known conversions,, bg 

WHILE phrase of LOOP instruction, 
White space, 

Whole numbers,, fj 

Whole numbers,checking with DATATYPE, 
Whole numbers, definition, 

WORD method,, 

WORDINDEX method, 

WORDLENGTH method,, [194] 

WORDPOS method, 

WORDS method,, 

Words, special,class, 

Words, special,sourceline, 
Words,counting, using WORDS, [194 
Words,deleting from a string, [184 
Words,extracting from a string, |192], f94) 
Words,finding in a string, 

Words, finding length of, [94] 

Words,in parsing, 

Words, Locating in a string, 
Words,special/ask, 
Words,special/digits, 
Words,special/form, 

Words, special/length, 
Words,special/null, 

Words, special/source, 
Words,special/super, 
Words,special/this, 
Words,special/trace, 








Words, special/version, 


X2B method,, 


X2C method,, 


X2D method, 
XOR, logical operator,, bg 


Zero character,escape sequence, pal 
Zeros,adding on the left, 
Zeros,padding, 


Zeros,removal with STRIP method, fia) 
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